Development Standards
Islumina is not a monolithic framework. Our core philosophy is modular composition.
All modules within the ecosystem adhere to strict architectural standards, ensuring developers can seamlessly introduce specific modules into their existing architecture without any overhead or framework lock-in.
Core Principles (Family Hard Rules)
Section titled “Core Principles (Family Hard Rules)”Every core package in the Islumina family strictly follows these architectural disciplines:
-
Zero Cross-Package Dependencies This is our most critical P0 standard. Every package (e.g.,
aifsmjsoraiecsjs) is completely independent and never depends on another package within the ecosystem. They come bundled with their necessary underlying implementations (such as standalone Event Emitters) to guarantee that installing a single package brings absolutely zero unnecessary coupling. -
Framework-Agnostic All packages are pure logic layer implementations. The source code never includes references to specific rendering engines (like PixiJS, Three.js) or UI frameworks (like React, Vue). They can be painlessly mounted in any browser, Node.js environment, or Web Worker.
-
Pure Dual Export (ESM + CJS) All modules are bundled via
tsup, fully supporting pure ESM and CommonJS dual exports, ensuring seamless integration regardless of your build tools. -
Strict Type Safety (TypeScript) Packages are developed with the strictest TypeScript configurations (enabling
strict,noUncheckedIndexedAccess,exactOptionalPropertyTypes) and completely prohibit the use ofany.
Package Roles & Basic Usage Guidelines
Section titled “Package Roles & Basic Usage Guidelines”While independent, each package is designed with a focused, Single Responsibility:
1. aifsmjs - Finite State Machine
Section titled “1. aifsmjs - Finite State Machine”A highly flexible FSM module supporting string-shorthand transitions, optional shared Contexts, and Hierarchical Sub-machines.
2. aiecsjs - Entity Component System
Section titled “2. aiecsjs - Entity Component System”A high-performance archetype-based ECS. It features ultra-fast forEachEntityIndexed iteration with recycle-safe array indexing. It supports entity Relations, delayed Commands, and logic delegation to SharedArrayBuffer (SAB) Workers.
3. aispritejs - State-Driven Sprite Animation
Section titled “3. aispritejs - State-Driven Sprite Animation”A runtime that drives state transitions mapped to animation frames via numbers, booleans, or triggers. Its core is fully renderer-agnostic, easily bridging with renderers like PixiJS through dedicated adapters.
4. aieventjs - Typed Event Emitter
Section titled “4. aieventjs - Typed Event Emitter”More than a simple Emitter, it supports time throttling (throttleMs), wildcard listeners, and advanced sampling rate execution (sampleRate).
5. aipooljs - Object Pooling
Section titled “5. aipooljs - Object Pooling”Standardized lifecycle management for objects. Focuses on safe borrow mechanisms and robust onOverflow handling.
6. aiquadtreejs - Spatial Partitioning Broadphase
Section titled “6. aiquadtreejs - Spatial Partitioning Broadphase”Designed for collision broadphase retrieval. It offers zero-allocation (zero-alloc) retrieveInto APIs, eliminating per-frame garbage collection (GC) pressure.
7. aiaudiojs - Audio System
Section titled “7. aiaudiojs - Audio System”A high-level wrapper built around Howler.js, focusing on lifecycle management and equal-power crossfades for game audio. (Note: A built-in synth is an explicit non-goal to keep the library lightweight).
8. aibridgejs - Communication Bridge
Section titled “8. aibridgejs - Communication Bridge”A pure-web safety label communication layer focused on data passing across different systems or environments (e.g., Main thread and Worker).