Package pajammin

Pajammin' is a side-scrolling video game where the main character explores the land of dreams, meets strange new people, encounters bizzare and dangerous creatures, and finds lots of stylin' pajamas.

Playing

To run pajammin on windows, double click on pajammin.pyw; to run pajammin on UNIX or OS X, run the pajammin script. (In either case, the pajammin package must be in python's path!)

[add instructions for playing here]

Requirements

Pajammin' requires Python 2.3+ and Pygame.

Architecture

The world of sleepyland is divided into levels, each of which is encoded with a single Level object. Each level is made up of discrete Entitys, including platforms, walls, ground, monsters, the player's avatar, and background decorations.

Each entity can own zero or more rectangular physical forms, or Bodys. Physical interactions between these bodies, such as collision detection, are handled by the PhysicsEngine.

Each entity can also own zero or more animated graphical widgets called Sprites. The display an animation of these sprites (and any other on-screen elements) is handled by the DisplayEngine.

Entities can be controlled by AI Scripts. Each script starts out as a list of tasks that should be performed in sequence. Tasks can optionally spawn sub-tasks, which should be completed before (or instead of) the main task, leading to a depth-first "tree" of tasks.

Top-level control-flow of the game is controlled by the GameEngine, which is responsible for updating the physics and display engines; the AI scripts; for calling the entities' individual update functions; and for handling user input. The game engine uses a Game object to store the current state of the game. In particular, the Game maintains a copy of every level that the player has explored; and a pointer to the current level. In order to save memory space, the Game object may store levels that the player is not currently exploring on disk.

The following diagram shows the basic architecture used by Pajammin'. The top portion contains the three engines that drive the game; and the lower portion contains the classes that store the game's state. But note that many of these data classes are themselves active. In particular, scripts and entities define many methods that modify their own state or the state of the world.:

####################################################################
#  ENGINES                                                         #
# +---------------+   owns +------------+ owns   +---------------+ #
# | DisplayEngine |<-------| GameEngine |------->| PhysicsEngine | #
# +---------------+ 1      +------------+      1 +---------------+ #
#          |                     | owns                  |         #
#..........|.....................|.......................|.........#
#  DATA    |                     V 1                     |         #
#          |                 +------+                    |         #
#          |                 | Game |                    |         #
#          |                 +------+                    |         #
#          |                     | owns                  |         #
#          |                     |                       |         #
#          |                     V 0+                    |         #
#          | controls      +-----------+        controls |         #
#          |               |   Level   |                 |         #
#          |               +-----------+                 |         #
#          |             owns |     | owns               |         #
#          |                  |     |                    |         #
#          |                  |     V 0+                 |         #
#          |                  |  +--------+              |         #
#          |                  |  | Script |              |         #
#          |                  |  +--------+              |         #
#          |                  |    | controls            |         #
#          |                  |    |                     |         #
#          V 0+            0+ V    V 1?                  V 0+      #
#     +--------+ 0+    owns +--------+ owns          +------+      #
#     | Sprite |<-----------| Entity |-------------->| Body |      #
#     +--------+            +--------+               +------+      #
####################################################################

Package Contents

The following table lists the modules and data files that make up the Pajammin' game, and gives a brief summary of the purpose of each one:

 scripts/
   pajammin .................. UNIX script to run Pajammin'
   pajammin.pyw .............. Windows script to run Pajammin'

 pajammin/
   cli.py .................... The command-line interface
   game.py ................... The game engine & the 'Game' data class
   level.py .................. The 'Level' data class
   physics.py ................ The physics engine
   input.py .................. Input event dispatcher
   consts.py ................. Definitions of shared constants
   iso3d.py .................. A file where I'm experimenting with doing 
                               isometric 3d display
 
   entitiy/ .................. Objects in the game
     entity.py ............... The 'Entity' base class
     agent/ .................. Entities that represent 'characters'
       agent.py .............. The 'Agent' base class & related classes
       avatar.py ............. The player's avatar entity
       walker.py ............. Agents that walk
       flyer.py .............. Agents that fly
     projectile.py ........... Projectiles (bullets, fireballs, etc.)
     environ.py .............. Entities that make up the environment
     mark.py ................. Short-lived entities with no body that show
                               some an action (eg an explosion).
       
   ai/ ....................... Artificial Intelligence
     script/ ................. AI scripts
       script.py ............. The 'Script' class & related classes
       default.py ............ Default script generator
       agent.py .............. Scripts for all agents
       walker.py ............. Scripts for walker agents
       farie.py .............. Scripts for farie
     pathplanner.py .......... Path planning
  
   display/ .................. Graphical display support
     engine.py ............... The display engine
     text.py ................. Text rendering
     image.py ................ Image loading & manpulation
     hud.py .................. The heads-up display
     sprite/ ................. Animated sprites
       sprite.py ............. The 'Sprite' data class & related classes
       *.py .................. Sprite category definitions
     ui/ ..................... User interface widgets
       button.py ............. Buttons
       menu.py ............... Menus
       textbox.py ............ Text boxes
       scrollbar.py .......... Scrollbars
   
   util/ ..................... Utility classes & functions
     grid.py ................. The ProximityGrid container datatype
     importlevel.py .......... Import from old pajammin levels
     profile.py .............. A simple profiler
     leveleditor.py .......... The level editor
     data.py ................. Path resolution for data files
   
   data/ ..................... Data files (i.e., non-python files)
     levels/ ................. Pickled 'Level' objects
     images/ ................. Image files (sprites, backgrounds, etc.)
     sounds/ ................. Sound files
     saves/ .................. Save games (each in a separate subdirectory)
     play/ ................... Swap space used by 'Game' to store levels
                               that the player is not currently exploring

Version: 0.6

Author: Edward Loper

To Do:

Level shouldn't keep its own list of sprites or bodies.
make entity maintain its own list of sprites/bodies, and add Entity.add_body, Entity.add_sprite, etc.
Scripts aren't organized by entity (except maybe in editor)
separate out direction vs side?? (up vs top?)
Add some abstract properties like 'intelligence' or 'aim' that are used by the AI scripts to decide, e.g., how precisely to aim.
Before saving a level, execute all after() callbacks.

Submodules

Submodules
`ai`: Artificial intelligence & scripting for Pajammin' entities. `pathplanner`: Path planning. `script`: AI scripting for Pajammin' entities. `agent`: AI script tasks for `Agent`s. `default`: The default script generator. `farie`: AI script tasks for `Farie`. `script`: AI scripting for Pajammin' entities. `walker`: AI script tasks for `Walker` agents. `cli`: Pajammin's command-line interface. `consts`: Definitions of shared constants. `display`: Graphical display support `engine` `hud`: The heads-up display, which provides the user with information about the state of the avatar and the world. `image`: Support for loading and manipulating images. `sprite`: Graphical widgets that defines one or more animation modes, based on images loaded from files. `agents`: Sprite categories for agents (other than the avatar). `avatar`: Sprite categories for the avatar and the avatar's pajamas. `decorations`: Sprite categories for decorations. `ground`: Sprite categories for ground entities. `marks`: Sprite categories for `Mark`s, or short-lived entities with no body that show that some action or event occured (such as an explosion). `platforms`: Sprite categories for platforms. `projectiles`: Sprite categories for projectiles. `sprite`: Graphical widgets that defines one or more animation modes, based on images loaded from files. `walls`: Sprite categories for walls. `text`: Support for rendering text. `ui`: User interface widgets, such as buttons and menus. `button`: Button user interface widgets. `menu`: Menu user interface widgets. `scrollbar`: Scrollbar user interface widget. `textbox`: Text box user interface widget. `entity`: Game objects, such as turtles, platforms, doors, and the player. `agent`: Characters in the world, such as turtles, snakes, and the player's avatar. `agent`: Characters in the world, such as turtles, snakes, and the player's avatar. `avatar`: The main character's avatar. `flyer`: Agents that can fly. `walker`: Agents that can walk and jump. `entity`: The base class for game objects, such as turtles, platforms, doors, and the player. `environ`: Entities that make up the environment, such as the ground, walls, and platforms. `mark`: Short-lived entities that consist of a single sprite, whose purpose is to show that some event occured (e.g., an explosion or an attack). `projectile`: Entities that represent 'projectiles,' such as fireballs or bullets. `game`: The `Game` data class and the `GameEngine`. `input`: The input handler for pajammin. `iso3d`: In this file, I'm experimenting with having select levels run in an isometric 3d mode, rather than the existing side-scroller mode. `level`: The `Level` data class, which keeps track of the entire state of a single level. `physics`: The physics engine, which implements the basic physics for the bodies of each entity. `util`: Utility classes and functions. `data`: Path resolution for data files. `grid`: The `ProximityGrid` container datatype, which organizes objects by their location. `importlevel`: An importer used to load old pajammin' levels. `leveleditor`: The pajammin' level editor. `profile`: A simple but flexible high-level profiler, used to keep track of how much time different tasks are taking.

ai: Artificial intelligence & scripting for Pajammin' entities.
- pathplanner: Path planning.
- script: AI scripting for Pajammin' entities.
  - agent: AI script tasks for Agents.
  - default: The default script generator.
  - farie: AI script tasks for Farie.
  - script: AI scripting for Pajammin' entities.
  - walker: AI script tasks for Walker agents.
cli: Pajammin's command-line interface.
consts: Definitions of shared constants.
display: Graphical display support
- engine
- hud: The heads-up display, which provides the user with information about the state of the avatar and the world.
- image: Support for loading and manipulating images.
- sprite: Graphical widgets that defines one or more animation modes, based on images loaded from files.
  - agents: Sprite categories for agents (other than the avatar).
  - avatar: Sprite categories for the avatar and the avatar's pajamas.
  - decorations: Sprite categories for decorations.
  - ground: Sprite categories for ground entities.
  - marks: Sprite categories for Marks, or short-lived entities with no body that show that some action or event occured (such as an explosion).
  - platforms: Sprite categories for platforms.
  - projectiles: Sprite categories for projectiles.
  - sprite: Graphical widgets that defines one or more animation modes, based on images loaded from files.
  - walls: Sprite categories for walls.
- text: Support for rendering text.
- ui: User interface widgets, such as buttons and menus.
  - button: Button user interface widgets.
  - menu: Menu user interface widgets.
  - scrollbar: Scrollbar user interface widget.
  - textbox: Text box user interface widget.
entity: Game objects, such as turtles, platforms, doors, and the player.
- agent: Characters in the world, such as turtles, snakes, and the player's avatar.
  - agent: Characters in the world, such as turtles, snakes, and the player's avatar.
  - avatar: The main character's avatar.
  - flyer: Agents that can fly.
  - walker: Agents that can walk and jump.
- entity: The base class for game objects, such as turtles, platforms, doors, and the player.
- environ: Entities that make up the environment, such as the ground, walls, and platforms.
- mark: Short-lived entities that consist of a single sprite, whose purpose is to show that some event occured (e.g., an explosion or an attack).
- projectile: Entities that represent 'projectiles,' such as fireballs or bullets.
game: The Game data class and the GameEngine.
input: The input handler for pajammin.
iso3d: In this file, I'm experimenting with having select levels run in an isometric 3d mode, rather than the existing side-scroller mode.
level: The Level data class, which keeps track of the entire state of a single level.
physics: The physics engine, which implements the basic physics for the bodies of each entity.
util: Utility classes and functions.
- data: Path resolution for data files.
- grid: The ProximityGrid container datatype, which organizes objects by their location.
- importlevel: An importer used to load old pajammin' levels.
- leveleditor: The pajammin' level editor.
- profile: A simple but flexible high-level profiler, used to keep track of how much time different tasks are taking.