Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


Leif Theden edited this page · 3 revisions
Clone this wiki locally

MH / Lib2d

lib2d is a game framework… pygame is mostly just functions to load images/sounds/input and run a clock….its not useful for making a game. lib2d is useful for platformers or zelda-type games.

there isn’t really much that is essential. lib2d just expects objects, an area, and TMX maps.

you would need: == game state (where you collect input and display avatars for your game) == a tmx map with control layer == some objects / avatars == a world builder script (called in MH) == a run script

in MH the files are: — kinda a test demo for a battle screen i never finished this — some constants for character status — special game state for cutscenes look in resources/scripts for the file that show the intro you can make others like it — makes dialogs with questions or just text — monster dna for random creatures never finished this — just has the loading screen — for enemies (“mobs”) not finished — i forgot :/ — pause screen — bit of code that reads the TMX map and moves the camera around and put tiles on the screen the main rendering functions are in lib2d/…but you won’t need to change it. — bits of misc rpg actions, pushing stuff, carrying things, etc — spells used in the battle — title screen — game state with a camera. this is where you play the game. this handles sound, controls, interactions, gui etc. you will spend a lot of time modifying this.

I’m glad you’re interested in it, but i’m afraid there isn’t much documentation. if you have questions, call me on skype, google hangouts, or irc.

my skype name is leif.theden im also on irc in #pygame. my handle is bitcraft

how to use lib2d? see the guide below

what's the concept behind it? the concept is using tiled to do all of the design, and python for the behavior

the game format is like a tree:

                  /   \
       areas    objects

more objects / etc

this tree is make in lib/

all objects can “add” other objects. the engine figures out how to use them. you can add sounds, animations, and even other objects to an object areas also hold objects

the maps are made in tiled and have a special ‘control’ layer. the control layer positions objects, sets metadata, and holds the level map

how is the workflow to make games with it? see the end of the guide

Is there any documentation that I could use? not much. there is some in the source code, and some below.

i’m going to use this email to write a wiki.

explore adventure games

this is an old version of the library. there are a couple easy-to-fix bugs: —dors dont work

explore platform games

download this game to see the code and play. i made it in a week for the pyweek game contest.

there are a few bugs: —not many sounds —jumping is awkward —you need to jump over the elevators

controls are Q W E and ENTER


lib2d has some nice features to make pygame games: —fast fullscreen scrolling —support for layers, so your character can hide behind trees, buildings, etc —basic physics —avatars (sprites) with many animations and directions —easy animation loading —controller and keyboard support (no need to change controls if using controller) —save and loading —some mouse functions —fast collision detection —menu / dialogs with a nice border —pathfinding (not tested much) —easy retro graphics (scaling)

lib2d relies on Tiled TMX maps for basically everything: —map data —collision areas (walls, etc) —object starting locations —some object metadata


almost any kind of game resources (image, sound, music) is handled by lib2d. there are a few shortcomings of pygame, so i’ve wrapped many parts of the loading to a way i like.

resources are stored in a simple folder structure called “resources"


all game objects can be loaded and saved.


avatars are used like pygame ‘sprites’, but support multiple animations and directions. animations and direction changes are handled automatically. avatars are also the class you will want to use to make the game…you can program them easily.


the engine opens ‘’ and runs build(). build() returns just one thing…an area object will all the things in the game.

  • lib/


all objects are persistent…so if a object or level changes and saved you can run the game for the old state. so save games are free…i haven’t tested this for a long time though. save games do not modify a level TMX


areas load data from a TMX map and then load the avatars / game objects, play music, run physics, etc

game state/context management

write your own ‘contexts’: title screen, gameplay, pause menu, etc

  • lib/
  • lib/

making your own game with lib2d

here is the basic work flow for a lib2d game:

—build your map (or a test map) in tiled —program your objects in ./lib/ —add the objects to the game ( —build your states (levelstate, titlescreen, etc) in ./lib/ —test!

tiled maps

when i began lib2d, tiled didn’t have very good functions for building objects… it has changed, it is easier in tiled now, but i still prefer this method:

use a ‘control layer’. this is a special tile layer with colored numbers. these numbers are the “GUID”, and can be used to place your walls and objects.

the control layer will not be seen when playing the game.

open resources/maps/level1.tmx to see how it is used.

Something went wrong with that request. Please try again.