Improve description and add better TODO planchicken-scheme-conversion

2 files changed, 134 insertions, 44 deletions

diff --git a/README.md b/README.md
index ffe301a..fb33a75 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,23 @@
 MACROKNIGHT
 ===========
 
-This is a game written for the [Spring Lisp Game Jam 2025](https://itch.io/jam/spring-lisp-game-jam-2025).
+This is a game originally written for the [Spring Lisp Game Jam 2025](https://itch.io/jam/spring-lisp-game-jam-2025).
 
 ## Dependencies
 
-This is a python game written with [Hy](https://hylang.org) and [Pygame](https://pygame.org). It requires the following to be installed:
+This is a game written with chicken-scheme and SDL2. It requires the following to be installed:
 
-- Python (3.9+)
+- chicken-scheme
 - SDL2
 
 ## Quickstart
 
-To install the python dependencies and run the game, simply type:
+To build the game, run
 
 ```
 make
 ```
 
-## Manual installation
-
-*Recommended* Create a virtual environment for the dependencies. On Debian-based distributions, you will need the package `python3-venv`. Run the following:
-
-```
-python3 -m venv venv
-. venv/bin/activate
-pip install -r requirements.txt
-```
-
-Then run the game with the venv active:
-
-```
-hy src/macroknight/game.hy
-```
-
-
 ## Credits
 
 - Code: Gene Pasquet
diff --git a/TODO.org b/TODO.org
index 95667a0..0b457c3 100644
--- a/TODO.org
+++ b/TODO.org
@@ -1,23 +1,130 @@
-* Bugs
-** DONE Collision detection when moving sideways and jumping
-** DONE Resolve collisions between each macro move
-** DONE Amount of movement from macros
-** TODO Better collision resolution
-** TODO Handle collisions in macro steps
-
-* Improvements
-** DONE Display each stage of macro execution with a timer
-** DONE Add enemies
-** DONE Create enemy classes and behaviour
-** DONE Flip player sprite when moving the other way
-** DONE Animate player sprite
-** DONE Add help text
-** DONE Add cool-down for macro ability
-** DONE Create more levels
-** DONE Define entity position on map layer
-** TODO Add a menu
-** TODO Killing enemies
-** DONE Detect win conditions
-** TODO Detect loss conditions
-** TODO Music
-** TODO Sound effects
+#+title: 2D Game Engine Development Plan
+
+* Implementation Plan: Plan A (Revised for Chicken Scheme Audio)
+
+** *Milestone 1: The Layered World & Core Data*
+*** TODO Update map parser to read layer information from the tilemap file. :graphics:parsing:
+*** TODO Modify the render loop to draw layers in a specified order.        :graphics:rendering:
+*** TODO Define the core `GameObject` or `Entity` data structure.           :game_objects:core:
+
+
+** *Milestone 2: A Visible, Controllable Entity*
+*** TODO Implement a system to load a texture and render it as a sprite. :graphics:rendering:sprites:
+*** TODO Build a map to store the current state of each key/button.      :input:core:
+*** TODO Process SDL events to update the input state map each frame.    :input:core:
+
+
+** *Milestone 3: Connecting Input to Action*
+*** TODO Update the player entity's velocity based on the input state map. :game_objects:physics:
+*** TODO In the update loop, update entity position based on its velocity. :physics:core:
+*** TODO Create a configurable mapping system (`KEY_W` -> `"move_up"`).    :input:actions:
+
+
+** *Milestone 4: A Scrolling Camera & Basic Physics*
+*** TODO Define a `Camera` and apply a rendering offset to all world objects. :graphics:rendering:camera:
+*** TODO Make the camera's position update to follow the player entity.       :graphics:rendering:camera:
+*** TODO Implement a basic physics update that applies gravity to entities.   :physics:gravity:
+
+
+** *Milestone 5: World Collision*
+*** TODO Create a function that gets the properties of a tile at a world coordinate. :physics:collision:tilemap:
+*** TODO Check an entity's bounding box against nearby solid tiles.                  :physics:collision:tilemap:
+
+
+** *Milestone 6: Scene Management & A Simple Enemy*
+*** TODO Implement a system to load a level and instantiate all game objects. :scene_management:core:
+*** TODO Manage the main game loop, calling `update` for all active objects.  :scene_management:core:
+*** TODO Implement a basic FSM for an enemy with "idle" and "patrol" states.  :ai:fsm:
+
+
+** *Milestone 7: Interactive Entities & Visual Polish*
+*** TODO Write the core AABB function that checks for an overlap.              :physics:collision:aabb:
+*** TODO Create a system to check for and resolve collisions between entities. :physics:collision:entities:
+*** TODO Implement support for animated tiles (e.g., water, torches).          :graphics:rendering:animation:
+
+
+** *Milestone 8: The Audio Engine Foundation*
+*** TODO Create the FFI bindings for the essential SDL2_mixer C functions.             :audio:ffi:bindings:
+*** TODO Using the new bindings, initialize the library and create a resource manager. :audio:core:resource_management:
+*** TODO Write a wrapper function like `(play-sound 'collision)` and trigger it.       :audio:api:
+
+
+** *Milestone 9: UI & Advanced AI*
+**Goal:** Display information to the player and give enemies intelligent navigation.
+
+*** TODO Integrate the SDL2_ttf library and write a function to render text.  :ui:text:rendering:
+*** TODO Implement the core data structures for A* (nodes, open/closed sets). :ai:pathfinding:a_star:
+*** TODO Write the main A* algorithm loop to find a path on the tile grid.    :ai:pathfinding:a_star:
+
+
+** *Milestone 10: Data-Driven Logic in Scheme*
+*** TODO Design a system to define entity "prefabs" in separate `.scm` files. :engine:core:architecture:data_driven:
+*** TODO Implement logic to `load` or `eval` these files at runtime.          :engine:core:architecture:data_driven:
+
+
+* Task Documentation
+  This section provides a high-level overview and purpose for each major feature of the game engine.
+
+** Graphics & Rendering
+*** Implement Tile Layers for depth
+    This task involves modifying the rendering system to handle multiple tile layers. By drawing a background layer, a main gameplay layer, and an optional foreground layer in order, the engine can create a sense of depth and visual complexity, enabling effects like parallax scrolling.
+
+*** Support for Animated Tiles
+    This feature brings static tilemaps to life. It requires a system to associate specific tile IDs with animation data (a sequence of frames and timings). The renderer will then select the correct frame based on the current game time, creating effects like flowing water or flickering lights.
+
+*** Create a Camera system for scrolling
+    The camera is the player's window into the game world. This task involves creating a virtual camera that defines a rectangular viewport. All game objects will be rendered relative to the camera's position, allowing for smooth scrolling through levels that are larger than the screen.
+
+*** Implement a Sprite rendering system
+    This is the core system for drawing any non-tilemap graphics, such as players, enemies, and items. It will be responsible for loading textures (often from a single "texture atlas") and drawing specific rectangular portions of them to the screen.
+
+*** Add Parallax Scrolling
+    A visual effect that enhances the illusion of depth. By moving background layers at a slower rate than the main gameplay layer, it simulates distance. This task involves assigning a scroll factor to each layer and applying it during the render step.
+
+** Game Objects & Scene Management
+*** Design a base "Game Object" or "Entity" class
+    This is the fundamental building block for everything in the game world. This task involves defining a core data structure that holds common properties like position, velocity, and size, and can be extended with components for specific behaviors (e.g., rendering, physics).
+
+*** Create a Scene/Level manager
+    The scene manager is the conductor of the game. It is responsible for loading a level's data, instantiating all the necessary game objects, and orchestrating the main game loop by calling the `update` and `render` functions for every active object.
+
+** Physics & Collision
+*** Implement Axis-Aligned Bounding Box (AABB) collision detection
+    This is the simplest and most common form of 2D collision detection. The task is to write the core mathematical function that checks if two rectangular bounding boxes are overlapping, which forms the basis for all entity-to-entity interactions.
+
+*** Add collision between entities and the tilemap
+    This feature makes the game world "solid." It involves creating a system that checks an entity's position against the tilemap grid to prevent it from moving through tiles marked as impassable, and to allow it to stand on platforms.
+
+*** Implement simple physics
+    This task introduces basic physics simulation. At its core, this means applying forces like gravity to an entity's acceleration, using that to modify its velocity, and finally using the velocity to update its position each frame.
+
+** Input
+*** Create an input handler
+    This is the low-level system that interfaces with SDL2 to read the state of the keyboard and gamepads. Its job is to poll for events each frame and store the current state (e.g., key down, key up, key held) in an easily accessible data structure.
+
+*** Map raw inputs to abstract game actions
+    This system decouples game logic from specific keys. Instead of checking if "W" is pressed, the game code will check if the "move_up" action is active. This makes input remapping simple and the code cleaner.
+
+** Audio
+*** Create SDL2_mixer bindings for Chicken Scheme
+    Since official bindings don't exist, this critical task involves using Chicken Scheme's Foreign Function Interface (FFI) to create Scheme procedure bindings for the C functions in the SDL2_mixer library (e.g., `Mix_Init`, `Mix_LoadWAV`, `Mix_PlayChannel`).
+
+*** Integrate the audio mixer
+    Using the newly created bindings, this task involves writing a higher-level audio manager for the engine. It will handle initializing the audio system, loading sound files into memory, and providing simple functions like `(play-sound 'name)` for the rest of the engine to use.
+
+** UI & HUD
+*** Integrate a font rendering library
+    This task involves integrating the SDL2_ttf library to enable the rendering of text. It includes loading TrueType Fonts (TTF) and creating a function to turn a string of text into a drawable texture.
+
+*** Create basic UI elements
+    This involves building a simple system for rendering user interface elements on screen, independent of the game world camera. Examples include displaying text for a score or drawing rectangles to represent a health bar.
+
+** Game AI
+*** Implement a Finite State Machine (FSM)
+    An FSM is a common pattern for managing AI behavior. It defines a set of states (e.g., `idle`, `patrol`, `chase`, `attack`) and the rules for transitioning between them. This keeps AI logic organized and easy to debug.
+
+*** Add A* pathfinding
+    This is a classic algorithm that allows an AI entity to find the shortest path between two points on a grid while avoiding obstacles. It is essential for creating enemies that can intelligently navigate the game world to chase the player.
+
+*** Data-Driven Logic in Scheme
+    This architectural task involves designing the engine so that entity types and behaviors are defined in external `.scm` files instead of being hardcoded. The engine will `load` or `eval` these files at runtime, allowing for rapid iteration and modification of game logic without recompiling.