diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2678a40
--- /dev/null
+++ b/README.md
@@ -0,0 +1,175 @@
+#HyperKaos engine
+
+##Engine.c
+
+###loadImage(char* filename)
+
+returns an SDL_Surface* of the image file at given file path
+
+###applySurface(int x, int y, SDL_Surface* src, SDL_Surface dest, SDL_Rect* clip)
+
+wrapper for SDL_BlitSurface, drawing src onto dest with origin (x,y) and clipped according to clip
+
+###getPixel(SDL_Surface* surface, int x, int y)
+
+get color value of a pixel on an SDL_Surface as a Uint32
+
+###scaleScreen()
+
+scales the game widow from native resolution of 320x180 to integer multiple according to config.h
+
+###loadBGM(char* filename)
+
+sets hasMusic for this map chunk to True and returns the file as a Mix_Music*
+
+###loadSFX(char* filename)
+
+returns a Mix_Chunk* of the wav file at given path
+
+###renderBackground()
+
+paints the current room's background image and increment its animation
+
+###renderForeground()
+
+paints the current room's fg objects and people, and the player
+
+###renderHUD()
+
+paints the spell selection HUD
+
+
+###interact()
+
+grabs keyboard input in the main loop and modifies the game state
+
+###kListen()
+
+checks if spell has been cast; if so, looks up the spell in the spellbook and does a synergy; then unsets the spell lookup;
+then checks if any eventTriggers have been activated; due to the implementation of hyperKaos, if more than one are activated at the same time, the one later in the array is run
+
+###init(int argc, char** args)
+
+initializes SDL subssytems, creates game window, loads UI data and hero data, allocates memory for mapData and mapBuffer, dialogueData, kaosData, theatre (scene data), and builds the spellbook
+
+###writeSpellbook()
+
+builds some hyperKaos* and stores them in spellBook
+
+###burnSpellbook()
+
+deallocates spellbook Memory
+
+###toggleFullscreen()
+
+reinvents the wheel with SDL_SetVideoMode
+
+###timeDilation()
+
+waits with SDL_Delay to keep a constant framerate
+
+###frameAdvance()
+
+scales the internal screen to the game window size, updates the game window, and waits to start the main loop over
+
+###cleanup()
+
+enters windowed mode, cleans up all the memory, closes SDL subsystems
+
+###intro()
+
+builds a couple Scene*s for the intro sequence, plays them, and cleans up the memory.
+
+###mainmenu()
+
+listens for keyboard input and navigates the main menu. reads save file if continued game, otherwise sets game data to the beginning of the game. or quit. takes control of the main game loop
+
+###pausemenu()
+
+listens for keyboard input and saves, quits, or continues playing; takes control of the main game loop
+
+##WorldData.c
+
+###bufferData(int chunk)
+
+sets hasMusic to flase, paints loading message on screen, builds world chunk; if there is an error building the world, quit the game
+
+###hashCmd(char* x)
+
+return an 8bit hash on a string for interpreting the worldBuilder script (this means there are max 256 commands for map generation, excluding "<" which functions as a closing bracket for "if" and "ifNot" directives)
+
+###worldBuilder(int chunk)
+
+allocates memory, opens map data file for current chunk; reads line by line, hashing the first word of the line, then switching on that to execute an action; bubbles up failure (malformed lines) by returning nonzero; returns zero if the whole file is read and processed
+
+###buildBGM(char* props)
+
+parses the args of loadBGM worldBuilder command and passes them to loadBGM(); return nonzero if malformed
+
+###buildSFX(char* props)
+
+parses the args of loadFX worldBuilder command and passes them to loadSFX(); return nonzero if malformed
+
+###buildRoom(char* props)
+
+parses the args of mkRoom worldBuilder command to build a room and place it in mapBuffer; return nonzero if malformed
+
+###buildTextBox(char* props)
+
+parses the args of mkTextBox worldBuilder command to build an empty textBox and place it in dialogueData; return nonzero if malformed
+
+###modTextBox(char* props)
+
+parses the args of addText worldBuilder command to add text to the indicated textBox in dialogueData; return nonzero if malformed
+
+###buildSynergy(char* props)
+
+parses the args of addSigil worldBuilder command to pass to addSigil(); return nonzero if malformed
+
+###buildKaos(char* props)
+
+parses the args of mkKaos worldBuilder command, switches on the class to figure out which constructor to pass the subsequent args to returns nonzero if malformed
+
+###buildObstruction(char* props)
+
+parses the args of addObstruction worldBuilder command, passes them to addObstacle(); returns nonzero if malformed
+
+###buildFGImage(char* props)
+
+parses the args of addImg worldBuilder command and passes them to addFGObj(); returns nonzero if malformed
+
+###buildWarp(char* props)
+
+parses the args of addWrap worldBuilder command and passes them to addWarp(); returns nonzer o if malformed
+
+###buildHyper(char* props)
+
+parses the args of addTrigger worldBuilder command and passes them to addTrigger(); returns nonzero if malformed
+
+###chainKaos(char* props)
+
+parses the args of the chainKaos worldBuilder command and passes them to addKaos(); returns nonzero if malformed
+
+###buildPerson(char* props)
+
+parses the args of the addPerson worldBuilder command and passes them to addPerson(); returns nonzero if malformed
+
+###countMapThings(int* count, int chunk)
+
+writes counts of global memory objects in this chunk to count based on mapdata file; this means the map data must be read again to count global objects before deletion!
+
+###dataPurge(int* counts)
+
+takes counts produced by countMap to free map chunk data
+
+###unloadData(int chunk)
+
+allocates count buffer for global map objects, counts the objects with countMapThings(), and passes it to dataPurge()
+
+###pushBufferData()
+
+moves mapBuffer to mapData and allocates new mapBuffer; if music was loaded in the new map chunk, play the first track
+
+###pager()
+
+if the player is warping to a new map chunk, halt the music (if any), unload the current map chunk before pushing mapBuffer to mapData
\ No newline at end of file