LUMINSim Documentation

LUMINSim Documentation

This is an ongoing page as I (Andrew Mattson) document LUMINSim's current systems. This page is a major work in progress; feel free to add to it!

Going forward, I hope to add in-depth descriptions of the inner workings of each major system, including:

• Power
• Tools and tool swapping
• Terrain
• Multiplayer
• Each user-controlled scene (robots and astronaut)
• The UI (multiplayer menu, settings menu, keybind menu)
• Each (largely) independent scene and corresponding system(s) (brick maker, dirt spawner, tool spawner, etc.)

Getting Started

To learn how to get started with development yourself, visit the repository's README and follow the steps there to get the project set up.

Known Issues

The following are known issues that continuously plague the simulator.

Major Issues

Major issues are detrimental to fundamental functionalities of the simulator. Generally they have no known fix without major redesign of the system itself and adjacent systems.

• With no consistency or known cause, some BetterHingeJoint3D (see Classes) joints are floppy noodles. If you create a joint and it works at first, it will continue to work, but if it is a floppy noodle at first, it will always be a floppy noodle. Deleting and re-instantiating the joint scene does not seem to work.

Minor Issues

Minor issues are just annoying. Generally they have workarounds or can simply be ignored.

• The multiplayer synchronizers throw errors when connecting/disconnecting. No impact on multiplayer functionalities has been observed.

Repository Structure

• src/ – C++ GDExtension code for terrain and registration. Likely to be deprecated. See Terrain System (C++).
• demo/ – Godot project containing levels, assets, and GDScript systems.
  • export_presets.cfg – Information for Godot on how to export the project into platform-native forms. Created automatically by the Godot export menu.
  • game_manager.gd – Handles the majority of the multiplayer logic, especially the sending of data between the clients and the server. See Networking and Multiplayer.
  • project.godot – The main project file. Contains general project configurations and properties. This is the primary reference point for the Godot Engine when developing this project.
  • demo/astra – Files pertaining to the drivable Astra robot.
  • demo/astronaut – Files pertaining to the in-game, procedurally-animated astronaut character. See Astronaut Character.
  • demo/bin – Files pertaining to the compiled GDExtension binaries. Likely to be deprecated. See Terrain System (C++).
  • demo/components – Contains components or component-like scenes and related files. See Classes.
  • demo/environment – Files for the skybox (i.e., the stars in the sky).
  • demo/excahauler – Files pertaining to the drivable Excahauler robot.
  • demo/graphics – Contains many images for icons and textures, especially for the user interface. See User Interface.
  • demo/landers – Contains directories for different lunar landers. Landers are currently just static models.
  • demo/levels – Contains the main playable (i.e., non-UI) scenes and related files. See Levels.
  • demo/objects – Contains non-static (i.e., movable RigidBody3D) objects. See Objects.
  • demo/static_objects – Contains static (i.e., unmovable StaticBody3D) objects and their related code. See Static Objects.
  • demo/terrain – Scenes and files pertaining to the dynamic (i.e., mineable) terrain. See Terrain System (C++).
  • demo/terrain_fixed – Scenes and files pertaining to the static (i.e., unchanging) terrain. See Terrain System (C++).
  • demo/util – Scenes and files pertaining to UI as well as other useful scripts. See User Interface.

In-depth repository structure documentation (brief descriptions on a per-scene basis) may be created here by anyone.

Classes

The following scripts (ordered alphabetically, ignoring case conventions) register custom nodes with the keyword class_name:

• autonomy_component.gd → AutonomyComponent – simple navigation helper for NPC robots. See Autonomy System.
• better_hinge_joint_3d.gd → BetterHingeJoint3D – wrapper over Generic6DOFJoint3D for motorized joints that better simulate joints driven by hydraulics or linear actuators.
• bucket_attachment.gd → Bucket – digs into terrain to collect dirtballs. See Tools and Attachments.
• charge_component.gd → ChargeComponent – tracks battery state and handles charging/discharging. See Power System.
• connector_component.gd → Connector – area detector system useful in many contexts, including tool couplers and charge stations.
• dem_loader.gd → DemLoader – loads fixed DEM heightmaps and extends TerrainStatic256, which is declared via GDExtensions. See Terrain System (C++).
• forks.gd → Forks – tool attachment for moving objects. See Tools and Attachments.
• saw_blade_attachment.gd → SawBlade – spinning blade for cutting objects. See Tools and Attachments.
• tool_attachment.gd → ToolAttachment – base class for all detachable tools. See Tools and Attachments.
• ToolCouplerComponent.gd → ToolCoupler – manages attaching tools to a robot via physics joints. See Tools and Attachments.

Autonomy System

The current autonomous driving logic is implemented by the AutonomyComponent script. Every robot scene instantiates this node under its root VehicleBody3D.

Currently, this is how it works:

• A child NavigationAgent3D computes a path when pathfind_to(target_pos) is called.

• During _physics_process() the component steers the robot toward the next path point using the get_drive() and get_steer() helpers.

• The helpers are polled by astra_3d.gd so the component effectively overrides manual controls when active.

• If progress stalls the script nudges the body upward and forward to get free. Once the destination is reached the have_arrived flag is set.

Proposed External API

To enable players to program autonomy from outside the engine, a new AutonomyServer node could expose a local API via WebSocket, HTTP, or MQTT. The simulator would send each robot's state to this server, including data like true position, velocity, tool data, and battery level data, and eventually realistic simulated sensor data. An external script could connect to the API and issue commands such as drive, steer, actuate arm, and so on.

This approach decouples vehicle logic from the engine so users can iterate on autonomy in any language without recompiling the project. The AutonomyServer would relay commands to the relevant nodes (mirroring the current get_drive() and get_steer() methods) while still supporting multiplayer authority checks via GameManager.

Terrain System (C++)

C++ based GDExtensions currently provide the terrain implementation and will be replaced in the future with a more developer-friendly system.

Terrain Nodes

The terrain nodes let you represent static or dynamic terrain. They can be nested in other Node3Ds or offset around, but should not be scaled.

Static Terrain

TerrainStatic256 loads heightmaps and generates render and collision meshes. It stores a 256x256 heightmap, normally loaded from an EXR float height image scaled to -10000 meters (black) to +10000 meters (white).

• `fill_from_image(dem:Image, pixel_spacing:float)` takes an image and pixel spacing in meters to create the height map.
• `add_mesh(shader:Shader,casts_shadows:bool)` creates a mesh for rendering, using the specified shader.
• `add_static_collider()` creates a StaticBody3D with a CollisionShape3D of our heightmap, so physics interacts with the terrain.

Dynamic Terrain

TerrainSim extends TerrainStatic256 to simulate excavation, landslides, and merging dirtballs back into the heightmap. It stores a dynamic mineable 256x256 heightmap and inherits from TerrainStatic256.

• excavate_point(world:Vector3, dirtball_offset:Vector3, spawn_vel:Vector3) to excavate terrain into dirtballs. Any locations needing dirtablls will emit the signal `spawn_dirtball` with a spawn position and velocity as Vector3.
• try_merge(dirtball:Node3D) to merge dirtballs back down onto the terrain.

Terrain Tools

Scripts such as dirt_spawner.gd and dirtball.gd spawn and merge mobile particles with the dynamic terrain.

Power System

Movable vehicles include a ChargeComponent (see Classes) that stores amp-hours and battery percentage. Robots consume charge while driving or actuating, and static objects like charge stations or solar panels provide power when connected.

Tools and Attachments

All interchangeable implements derive from ToolAttachment. Robot arms have ToolCoupler nodes that detect nearby Connector areas and create physics joints to attach or detach tools. Available tools include the Bucket, Forks, and SawBlade (see Excavation Tools under Robot Systems). tool_spawner.gd respawns tools removed from its bays. To find where each of these classes are declares, see Classes.

Robot Systems

Astra Robot

The main scene is astra_3d.tscn. astra_3d.gd handles driving, energy usage, and tool attachment. It works with astra_arm_3d.gd and astra_hopper_3d.gd and their associated .tscn files for the robot's arm and hopper.

Astronaut Character

astronaut_character_3d.gd provides walking and camera control for a procedurally animated astronaut. We hope to implement VR for the astronaut in the future.

Excavation Tools

Attachments such as the bucket, forks, and saw blade extend ToolAttachment (see Classes) for various tasks. The files for these attachments are currently in Astra's directory, but this is subject to change.

Excahauler Robot

The main scene is excahauler_3d.tscn. Unlike Astra's implementation, all functionalities are within a single .tscn file and a few associated .gd files. Currently, only Excahauler's main arm (boom, stick, and tilt) is implemented, as trying to set up the scoop (fork and dump) joints in an identical way results in uncontrollable, noodle-like joints (See Major Issues).

Objects

Movable, physics-enabled props used primarily for construction.

• Madsen Cinder Block – a simple RigidBody3D brick spawned by brick_maker.gd. Designed by Elliott Madsen.

• Truss Modules – sets of 1m and 3m segments with collision shapes for stacking into arches, garages or other structures. These are modeled after the L-Truss design seen in our 2025 X-Hab project.

Static Objects

Charge stations and solar panels (see Power System), tool spawners, and other generally useful environment pieces. These scenes generally work independently of other scenes, and include:

• brick_maker.gd – creates bricks when filled with loose dirt.
• tool_spawner.gd – keeps bays stocked by respawning assigned attachments when they are taken.
• dirt_spawner.gd – continuously emits dirtballs for terrain testing, currently toggle-able by pressing X.

Networking and Multiplayer

game_manager.gd manages synchronized player/object data and signals for network updates. multiplayer_menu.gd lets players host or join games, start sessions, and handle disconnects.

User Interface

The ui.gd, joystick.gd, and keybinds_menu.gd scripts provide HUD elements, customizable input bindings, and on-screen controls for mobile users.

Command Line Interface

The user interface includes a command line interface (opened by pressing f1 if you are in a local game or are the host) with the following commands:

• goto X Y Z – Pathfind to the entered coordinates. Not working until a new autonomy system is implemented.
• respawn – Teleport back to the starting position.
• move X Y Z – Teleport to the given coordinates relative to your current position.
• grav X – Change the gravity to X m/s²
• tp X Y Z – Teleport to the given coordinates relative to the world origin.
• freecam – Enter a freecam state.
• simrate X – Change the speed of the simulation to X times normal speed.
• pause – Pause the simulation. Useful for capturing cinematics (freecam functionality still works, for example).

Cameras and Controls

movable_camera_3d.tscn and freecam.tscn implement user-controlled cameras.

Levels

Scenes in demo/levels/ (e.g., main3D.tscn with script main3D.gd) instantiate players, objects, and the terrain simulator, driving the overall simulation loop.

Future Work

The repository is under active development. Planned areas of documentation include deeper explanations of the power system, tool workflow, and multiplayer networking. Below are the current plans for LUMINSim to turn it into a commercial product. All contributions are welcome!

The idea of this breakdown is to first write the idea for implementation under the heading, and then update it over time to reflect the real implementation as it is completed. This might also include changing headings as we progress. These things do not necessarily have to be completed in order, as many systems can be created and made to work together over time. This can then be used as a direct reference for creating documentation once pushed.

1. Terrain Streaming System

1.1. Design chunk-based terrain data model (glTF/GLB)

WIP

1.2. Implement terrain export pipeline (server-side)

WIP

1.3. Develop server API for terrain distribution

WIP

1.4. Integrate client-side terrain streaming and chunk loading in Godot

WIP

1.5. Add terrain caching for offline/local testing

WIP

2. Challenge Framework

2.1. Define challenge types (e.g., unloading, excavation, structure building)

WIP

2.2. Implement challenge UI and timers

WIP

2.3. Track and store performance metrics locally

WIP

2.4. Integrate results with leaderboard backend (see 5.3)

WIP

3. Robot Autonomy Interface

3.1. Define LUMINSim scripting API (for movement, sensing, etc.)

WIP

3.2. Implement local scripting sandbox (Python or simplified API)

WIP

3.3. Add ability to deploy user scripts to control robots in challenge mode

WIP

4. Simulated Sensor Suite

4.1. Implement simulated IMU and encoder feedback

WIP

4.2. Implement LIDAR (2D/3D) and depth camera sensors

WIP

4.3. Expose sensor data via scripting API

WIP

4.4. Visualize sensor outputs in debug/test modes

WIP

5. Account & Leaderboard System

5.1. Build account creation and login system (email/password or OAuth)

WIP

5.2. Set up secure backend server with user profiles and authentication

WIP

5.3. Implement leaderboard storage for challenge scores

WIP

5.4. Create frontend UI for viewing and submitting records

WIP

5.5. Implement reward system hooks (for future prize/cosmetic integration)

WIP

6. LunaNet / Artemis Protocol Simulation

See LUMIN for more information.

6.1. Define safety zone data format and map overlay

WIP

6.2. Define safety zone defaults and rules

WIP

6.3. Notify players of violations with UI feedback or in-sim events

WIP

6.4. Enforce safety zones (LAMP intervention, LunaNet cutoffs)

WIP

6.5. Log compliance for integration with challenge scoring

WIP

7. Steam & Web Demo Packaging

7.1. Configure Godot project export for Steam

WIP

7.2. Create stripped-down web demo with limited map and challenge

WIP

7.3. Prepare demo marketing assets (logo, screenshots, description)

WIP

7.4. Set up Steam store page and submission

WIP

7.5. Deploy web demo on auroraroboticslab.com or similar

WIP

8. Testing & QA

8.1. Write unit tests for API and terrain loading

WIP

8.2. Conduct user testing of challenge flows and scripting

WIP

8.3. Optimize performance for low-end systems (especially web demo)

WIP

8.4. Fix usability issues and polish UI for MVP release

WIP