Module documentation

README.org

@@ -48,23 +48,100 @@ When a resource, such as a font or texture, is loaded from the filesystem, the p
 When records are first loaded, a finalizer is set for them ensuring they are unloaded when collected by the GC.
 If the game attempts to load a resource which has already been loaded, it will use the pointer in the ~resources~ hash table instead.
 
-* Structure & Modules
+* Folder Structure & Module Documentation
 The ~engine~ folder contains core engine code, organised across the following modules:
-- ~(engine core)~ which contains core functionality including starting the window and game loop, and functions for adding/removing systems, entities, and event buses to/from the game state.
-- ~(engine components)~ which contains methods for creating and accessing components.
-- ~(engine systems)~ which contains functions for creating new systems.
-- ~(engine events)~ which contains functions for creating and interacting with event buses.
-- ~(engine resources)~ which contains functions for loading and using resources.
-- ~(engine utilities)~ which contains generic engine utility functions.
-- ~(engine debug)~ which contains parameters and functions for debugging and profiling.
-- ~(engine math)~ which contains utility math and randomness functions.
-
-The ~components~ folder contains pre-made components, entities, and systems for ease of use:
-- ~(components ui)~ contains building blocks for basic UI elements.
-- ~(components 2d)~ contains building blocks for basic 2D elements.
-
 The ~games~ folder contains various sample games made with Imugi.
+** ~(engine core)~
+~(engine core)~ contains the fundamental engine functions. Entire games can be made using just the core module, and all other modules simply extend this module.
 
+*** Game State
+~world~ is an SRFI-69 hash table, which contains all entity component lists keyed by their symbol name.
+
+~component-sets~ is an SRFI-69 hash table, which contains an SRFI-113 set for every component type in the ~world~. Each set contains a symbol referencing a ~world~ entity that has a component of that type.
+
+~systems~ is a list, which contains all lists to be executed on each frame.
+
+~event-buses~ is an SRFI-69 hash table, which contains hash tables keyed by the event bus name. Each hash table in ~event-buses~ keeps track of individual event records keyed by action names.
+*** Entities
+#+begin_src scheme
+  (create-named-entity id . components)
+  (create-entity . components)
+  (remove-entity id)
+  (get-entity id)
+  (clear-world)
+#+end_src
+Functions for creating, removing, and fetching entities. ~id~ must be a symbol, and each parameter passed in as ~components~ must be an SRFI-99 record.
+
+When entities are created or removed, the creation/deletion is added to an internal queue. Entity creation and removal to/from the ~world~ state from the queue is performed at the top of each frame, or when ~(resolve-queues)~ is executed.
+*** Systems
+#+begin_src scheme
+  (make-system name rendering priority criteria process)
+  (system? record)
+  (system-name system)
+  (system-rendering system)
+  (system-priority system)
+  (set-system-priority! system priority)
+  (system-criteria system)
+  (set-system-criteria! system criteria)
+  (system-process system)
+  (set-system-process! system process)
+#+end_src
+Functions for creating systems, which are SRFI-99 records. ~name~ must be a symbol, ~rendering~ must be a symbol and either ~3d~, ~2d~, ~screen~, or ~none~, ~priority~ must be an integer, ~criteria~ must be a list of symbols, and ~process~ must be a zero argument procedure.
+
+#+begin_src scheme
+  (add-system system)
+  (remove-system name)
+  (clear-systems)
+#+end_src
+Functions for adding and removing systems from process. ~system~ must be an SRFI-99 record, and ~name~ must be a symbol (which is used to identify a ~system~ record in the ~systems~ list).
+
+When systems are created or removed, the creation/deletion is added to an internal queue. System creation and removal to/from the ~systems~ list from the queue is performed at the top of each frame, or when ~(resolve-queues)~ is executed.
+*** Event Buses
+#+begin_src scheme
+  (register-event-bus name)
+  (remove-event-bus name)
+  (fetch-event-bus name)
+#+end_src
+Functions for creating, removing, and retrieving event buses. ~name~ must be a symbol referencing the bus name in the ~event-buses~ hash table.
+
+Event buses are added and remove immediately, without queuing.
+
+#+begin_src scheme
+  (push-event bus action event)
+  (peek-event bus action)
+  (pop-event bus action)
+#+end_src
+Functions for creating and fetching events. ~bus~ must be a symbol referencing a bus name, ~action~ must be a symbol referencing the name of the action, and ~event~ must be a record.
+
+~peek-event~ returns the event record but keeps the event in the event bus. ~pop-event~ returns the event record and removes it from the event bus.
+*** Frame Generation & Game Loop
+#+begin_src
+  *clear-color*
+#+end_src
+~*clear-color*~ is a parameter which expects a u8vector corresponding to a Raylib color.
+
+#+begin_src scheme
+  (resolve-queues)
+#+end_src
+~(resolve-queues)~ causes all queues to immediately resolve pending actions to the true game state.
+
+#+begin_src scheme
+  (next-frame)
+#+end_src
+~(next-frame)~ is a frame generation function. When called, it resolves all queues, then beings drawing. It then clears the window background to the ~*clear-color*~, and then executes all systems.
+*** Window Functions
+#+begin_src
+  *window-size*
+  *window-title*
+#+end_src
+~*window-size*~ is a parameter that expects a cons pair of two integers, where the first integer is the window width, and the second is the window height.
+
+~*window-title*~ is a parameter that expects a string, which is used for the window title.
+
+#+begin_src scheme
+  (create-window process: (next-frame) close-predicate: (window-should-close?))
+#+end_src
+~create-window~ creates a window using the window parameters described above, then enters a loop which runs the ~process:~ function (~next-frame~ by default) on each frame, unless ~close-predicate:~ (Raylib's ~window-should-close~ function by default) returns true, in which case the window is closed.
 * Dependencies
 The following Chicken dependencies are required:
 - raylib