How aicell-lab/micro-farm-js works
Main Components
• Entry & Initialization
– Key files: index.html, src/main.ts
– Role: The HTML page bootstraps the application, while the main.ts file initializes critical systems such as asset loading (from the public directory after running setup-assets.sh), configuration, and starting the simulation loop.
• Asset Management
– Directory: src/assets
– Components: assetLoader.ts, animationLoader.ts, modelLoader.ts, etc.
– Role: Responsible for loading and organizing 3D assets, URDF files, textures, and animations prior to the simulation rendering.
• Controllers & Input Handling
– Directories: src/ctrl and src/io
– Key files: playerController.ts, cameraController.ts, eventMediator.ts, inputListener.ts, keyboard.ts, mouse.ts
– Role: Manage user interactions and control logic. They bridge input events (keyboard/mouse) to changes in scene state and physical simulation.
• Entity and Setup Management
– Directories: src/entity and src/setup
– Key files: entity.ts, armState.ts, actorFactory.ts, roomObjectFactory.ts, constants.ts
– Role: Define simulation objects (like robotic arms, bubbles, optics units) and provide factory functions and constants for proper entity initialization.
• Physics Simulation
– Directory: src/physics
– Key files: physicsSystem.ts, physicsWorld.ts, physicsSync.ts
– Role: Perform physics simulation using Ammo.js. This subsystem computes physical interactions, updates positions, and interacts with URDF-based objects (e.g., robotic arms) even though integration is a work-in-progress.
• System Coordination & Rendering
– Directory: src/system
– Key files: sceneSystem.ts, rendering.ts, thirdPersonCamera.ts, window.ts, playerOpacity.ts
– Role: Central coordination of the runtime environment. The SceneSystem, for example, organizes the simulation loop (runSimulationLoop) which calls input processing, physics updates, UI interactions, and renders the scene using Three.js.
• User Interface (UI)
– Directories: src/ui and src/css
– Key files: uiController.ts, dialogController.ts, and multiple CSS files (e.g., base.css, style.css)
– Role: Manage DOM interactions, overlays, dialogs, and other visual elements that support user control and system feedback.
Relationships and Interactions
• Flow from Initialization to Runtime:
– The entry point (index.html) loads main.ts, which kicks off the application by loading assets (via the asset management system) and initializing the simulation loop.
• Integration of Subsystems:
– The simulation loop in sceneSystem.ts orchestrates various subsystems:
• It drives input handling (via src/io) to capture keyboard and mouse events.
• Updates are forwarded to controllers (src/ctrl) to modify entity states (e.g., player, robotic arms, tables).
• The physics subsystem (src/physics) is stepped forward to update object dynamics.
• The rendering system (src/system and Three.js) refreshes the scene based on the new states.
• UI events and adjustments are managed in parallel (src/ui).
• Communication Patterns:
– Use of an event bus and mediator (src/io/eventBus and src/ctrl/eventMediator) suggests loose coupling between system modules.
– Data flows from input to controllers, then to the simulation state/physics, and finally to rendering.
Architectural Patterns and Technologies
• Modular design: The project is separated into distinct domains (assets, controllers, physics, UI, etc.) each encapsulated in its own directory.
• Simulation loop: The continuous “runSimulationLoop” method (requestAnimationFrame-driven) that integrates input, physics, and rendering.
• Event-driven communication: Both the “EventMediator” and “EventBus” components underscore a decoupled event-driven architecture.
• Use of Vite for fast bundling and development, ensuring that changes across these systems are quickly reflected during development.
• Three.js based rendering is foundational for the 3D visualization; Ammo.js provides the physics simulation (albeit with custom scripts and workarounds for URDF integration).
Summarize the Essential Elements
– Main entry: index.html and src/main.ts
– Initialization: Asset loading (src/assets), setup and factories (src/setup)
– Core simulation loop: SceneSystem (src/system/sceneSystem.ts) coordinating input, physics (src/physics), controllers (src/ctrl), and UI (src/ui)
– External interfaces: User inputs (src/io) and DOM based UI (HTML + CSS)
– Architectural patterns: Modular design, event-driven communication and simulation loop.