LUMINSim Documentation - Revision history

Acmattson3: Added reference to RobotMoose YouTube video.

2025-08-02T01:18:53Z

Added reference to RobotMoose YouTube video.

← Older revision		Revision as of 17:18, 1 August 2025
Line 111:		Line 111:
	=== [[Astra]] Robot ===		=== [[Astra]] Robot ===
	The main scene is <code>astra_3d.tscn</code>. <code>astra_3d.gd</code> handles driving, energy usage, and tool attachment. It works with <code>astra_arm_3d.gd</code> and <code>astra_hopper_3d.gd</code> and their associated <code>.tscn</code> files for the robot's arm and hopper.		The main scene is <code>astra_3d.tscn</code>. <code>astra_3d.gd</code> handles driving, energy usage, and tool attachment. It works with <code>astra_arm_3d.gd</code> and <code>astra_hopper_3d.gd</code> and their associated <code>.tscn</code> files for the robot's arm and hopper.

			For more information and visuals, watch [https://www.youtube.com/watch?v=GwJjh-E93ZA&ab_channel=RobotMoose the RobotMoose YouTube video about Astra].

	=== Astronaut Character ===		=== Astronaut Character ===

Acmattson3: Added potential fix for BetterHingeJoint3D issue.

2025-07-10T20:39:25Z

Added potential fix for BetterHingeJoint3D issue.

← Older revision		Revision as of 12:39, 10 July 2025
Line 20:		Line 20:
	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.		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 [[LUMINSim Documentation#Classes\|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.		* With no consistency or known cause, some BetterHingeJoint3D (see [[LUMINSim Documentation#Classes\|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.
			** A potential fix is to completely redo BetterHingeJoint3D to work directly with transforms, but this has the side effect of making things ''much'' easier to break the sim if there isn't some sort of implementation of forces.

	=== Minor Issues ===		=== Minor Issues ===

Acmattson3 at 22:10, 9 July 2025

2025-07-09T22:10:32Z

← Older revision		Revision as of 14:10, 9 July 2025
Line 133:		Line 133:
	* <code>tool_spawner.gd</code> – keeps bays stocked by respawning assigned attachments when they are taken.		* <code>tool_spawner.gd</code> – keeps bays stocked by respawning assigned attachments when they are taken.
	* <code>dirt_spawner.gd</code> – continuously emits dirtballs for terrain testing, currently toggle-able by pressing <code>X</code>.		* <code>dirt_spawner.gd</code> – continuously emits dirtballs for terrain testing, currently toggle-able by pressing <code>X</code>.

			== Building ==
			Currently there is no built-in building system (see [[LUMINSim Documentation#2.1. Define challenge types (e.g., unloading, excavation, structure building)\|Future Work, Challenge Framework]]), but [[User:Lawlor\|Dr. Lawlor]] has begun work on '''[https://github.com/auroraroboticslab/buildot Buildot]'''.

			Working from Buildot, my ([[User:Acmattson3\|Andrew Mattson]]) idea is to have:

			* A separate builder interface (Buildot) in the simulator.
			* Users would have a way to select buildings made in Buildot and place them down as a holographic blueprint.
			** Once the user confirms where they want to place the building, the holographic disappears and the user is prompted to place components in certain locations or excavate areas.
			** For example, the [[NASA X-Hab 2025: Modular Robotic Construction\|X-Hab 2025]] arch would have the user place all of the anchors, then go to the truss segments and so on. We could even make it so that, to build the arch, the user must have a robot designated for holding up the structure and, as the build process progresses, it can lift the structure as needed.

	== Networking and Multiplayer ==		== Networking and Multiplayer ==
Line 183:		Line 193:

	==== 2.1. Define challenge types (e.g., unloading, excavation, structure building) ====		==== 2.1. Define challenge types (e.g., unloading, excavation, structure building) ====
	~~WIP~~		This requires we have a building system (see the stub for [[LUMINSim Documentation#Building\|Building]]).

	==== 2.2. Implement challenge UI and timers ====		==== 2.2. Implement challenge UI and timers ====

Acmattson3 at 21:26, 9 July 2025

2025-07-09T21:26:55Z

← Older revision		Revision as of 13:26, 9 July 2025
Line 159:		Line 159:

	== Future Work ==		== Future Work ==
	The repository is under active development. Planned areas of documentation include deeper explanations of the power system, tool workflow, and multiplayer networking. ~~Contributions~~ are welcome!		[https://github.com/auroraroboticslab/godotrobot/ 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

Acmattson3 at 21:13, 9 July 2025

2025-07-09T21:13:38Z

← Older revision		Revision as of 13:13, 9 July 2025
Line 46:		Line 46:
	** '''<code>demo/terrain</code>''' – Scenes and files pertaining to the dynamic (i.e., mineable) terrain. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].		** '''<code>demo/terrain</code>''' – Scenes and files pertaining to the dynamic (i.e., mineable) terrain. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].
	** '''<code>demo/terrain_fixed</code>''' – Scenes and files pertaining to the static (i.e., unchanging) terrain. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].		** '''<code>demo/terrain_fixed</code>''' – Scenes and files pertaining to the static (i.e., unchanging) terrain. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].
	** '''<code>demo/util</code>''' – Scenes and files pertaining to UI as well as other useful scripts. See [[LUMINSim Documentation#User Interface\|User Interface~~]] and [[LUMINSim Documentation#Additional Utilities\|Additional Utilities~~]].		** '''<code>demo/util</code>''' – Scenes and files pertaining to UI as well as other useful scripts. See [[LUMINSim Documentation#User Interface\|User Interface]].
	In-depth repository structure documentation (brief descriptions on a per-scene basis) may be created here by anyone.		In-depth repository structure documentation (brief descriptions on a per-scene basis) may be created here by anyone.

Line 102:		Line 102:

	== Power System ==		== Power System ==
	Movable vehicles include a '''ChargeComponent''' 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.		Movable vehicles include a '''ChargeComponent''' (see [[LUMINSim Documentation#Classes\|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 ==		== 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 [[LUMINSim Documentation#Excavation Tools\|Excavation Tools]] under [[LUMINSim Documentation#Robot Systems\|Robot Systems]]). <code>tool_spawner.gd</code> respawns tools removed from its bays.		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 [[LUMINSim Documentation#Excavation Tools\|Excavation Tools]] under [[LUMINSim Documentation#Robot Systems\|Robot Systems]]). <code>tool_spawner.gd</code> respawns tools removed from its bays. To find where each of these classes are declares, see [[LUMINSim Documentation#Classes\|Classes]].

	== Robot Systems ==		== Robot Systems ==
Line 138:		Line 138:

	== User Interface ==		== User Interface ==
	The <code>ui.gd</code>, <code>joystick.gd</code>, and <code>keybinds_menu.gd</code> scripts provide HUD elements, customizable input bindings, and ~~optional~~ on-screen controls for mobile users.		The <code>ui.gd</code>, <code>joystick.gd</code>, and <code>keybinds_menu.gd</code> 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 <code>f1</code> if you are in a local game or are the host) with the following commands:

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

	== Cameras and Controls ==		== Cameras and Controls ==
	<code>movable_camera_3d.gd</code> and <code>freecam.gd</code> implement user-controlled cameras.		<code>movable_camera_3d.tscn</code> and <code>freecam.tscn</code> implement user-controlled cameras.

	== Levels ==		== Levels ==
	Scenes in <code>demo/levels/</code> (e.g., <code>main3D.tscn</code> with script <code>main3D.gd</code>) instantiate players, objects, and the terrain simulator, driving the overall ~~game~~ loop.		Scenes in <code>demo/levels/</code> (e.g., <code>main3D.tscn</code> with script <code>main3D.gd</code>) instantiate players, objects, and the terrain simulator, driving the overall simulation loop.

	~~== Additional Utilities ==~~
	~~Miscellaneous helpers include <code>fps_counter.gd</code> for performance output and <code>freecam.tscn</code> which can be spawned via the command console for debugging or spectator play~~.

	== Future Work ==		== Future Work ==
	The repository is under active development. Planned areas of documentation include deeper explanations of the power system, tool workflow, and multiplayer networking. Contributions are welcome.		The repository is under active development. Planned areas of documentation include deeper explanations of the power system, tool workflow, and multiplayer networking. Contributions are welcome!

Acmattson3 at 03:07, 8 July 2025

2025-07-08T03:07:58Z

← Older revision		Revision as of 19:07, 7 July 2025
Line 118:		Line 118:

	=== [[Excahauler]] Robot ===		=== [[Excahauler]] Robot ===
	The main scene is <code>excahauler_3d.tscn</code>. Unlike [[LUMINSim Documentation#Astra Robot\|Astra's implementation]], all functionalities are within ~~that~~ <code>.tscn</code> file and ~~the~~ associated <code>.gd</code> ~~file~~. 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 [[LUMINSim Documentation#Major Issues\|Major Issues]]).		The main scene is <code>excahauler_3d.tscn</code>. Unlike [[LUMINSim Documentation#Astra Robot\|Astra's implementation]], all functionalities are within a ''single'' <code>.tscn</code> file and a few associated <code>.gd</code> 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 [[LUMINSim Documentation#Major Issues\|Major Issues]]).

	== Objects ==		== Objects ==

Acmattson3 at 02:56, 8 July 2025

2025-07-08T02:56:36Z

← Older revision		Revision as of 18:56, 7 July 2025
Line 121:		Line 121:

	== Objects ==		== Objects ==
	~~WIP~~.		Movable, physics-enabled props used primarily for construction.

			* Madsen Cinder Block – a simple RigidBody3D brick spawned by [[LUMINSim Documentation#Static Objects\|brick_maker.gd]]. Designed by [[User:Frozenstiff\|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 [[NASA X-Hab 2025: Modular Robotic Construction#The L-Truss System\|the L-Truss design seen in our 2025 X-Hab project]].

	== Static Objects ==		== Static Objects ==

Acmattson3 at 02:53, 8 July 2025

2025-07-08T02:53:22Z

← Older revision		Revision as of 18:53, 7 July 2025
Line 80:		Line 80:

	== Terrain System (C++) ==		== Terrain System (C++) ==
	C++ based GDExtensions currently provide the terrain implementation and ~~may~~ be replaced in the future with a more developer-friendly system.		C++ based GDExtensions currently provide the terrain implementation and will be replaced in the future with a more developer-friendly system.

	=== ~~Static~~ Terrain ===		=== Terrain Nodes ===
	~~<code>TerrainStatic256</code> loads heightmaps and generates render and collision meshes~~.		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.'''

	=== Dynamic Terrain ===		==== Static Terrain ====
	<code>TerrainSim</code> extends <code>TerrainStatic256</code> to simulate excavation, landslides, and merging dirtballs back into the heightmap.		<code>TerrainStatic256</code> 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 ====
			<code>TerrainSim</code> extends <code>TerrainStatic256</code> to simulate excavation, landslides, and merging dirtballs back into the heightmap. It stores a dynamic mineable 256x256 heightmap and inherits from <code>TerrainStatic256</code>.

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

	=== Terrain Tools ===		=== Terrain Tools ===

Acmattson3 at 02:44, 8 July 2025

2025-07-08T02:44:20Z

← Older revision		Revision as of 18:44, 7 July 2025
Line 50:		Line 50:

	== Classes ==		== Classes ==
	The following scripts register custom nodes with the keyword <code>class_name</code>:		The following scripts (ordered alphabetically, ignoring case conventions) register custom nodes with the keyword <code>class_name</code>:
	* <code>ToolCouplerComponent.gd</code> → '''ToolCoupler''' – manages attaching tools to a robot via physics joints.
	* <code>connector_component.gd</code> → '''Connector''' – area detector used by tool couplers and charge stations.
	* <code>autonomy_component.gd</code> → '''AutonomyComponent''' – simple navigation helper for NPC robots. See [[LUMINSim Documentation#Autonomy System\|Autonomy System]].		* <code>autonomy_component.gd</code> → '''AutonomyComponent''' – simple navigation helper for NPC robots. See [[LUMINSim Documentation#Autonomy System\|Autonomy System]].
	* <code>charge_component.gd</code> → '''ChargeComponent''' – tracks battery state and handles charging/discharging.		* <code>better_hinge_joint_3d.gd</code> → '''BetterHingeJoint3D''' – wrapper over <code>Generic6DOFJoint3D</code> for motorized joints that better simulate joints driven by hydraulics or linear actuators.
	* <code>better_hinge_joint_3d.gd</code> → '''BetterHingeJoint3D''' – wrapper over <code>Generic6DOFJoint3D</code> for motorized joints.		* <code>bucket_attachment.gd</code> → '''Bucket''' – digs into terrain to collect dirtballs. See [[LUMINSim Documentation#Tools and Attachments\|Tools and Attachments]].
	* <code>~~tool_attachment~~.gd</code> → '''~~ToolAttachment~~''' – ~~base class for all detachable tools~~.		* <code>charge_component.gd</code> → '''ChargeComponent''' – tracks battery state and handles charging/discharging. See [[LUMINSim Documentation#Power System\|Power System]].
	* <code>~~forks~~.gd</code> → '''~~Forks~~''' – ~~tool attachment for moving objects.~~		* <code>connector_component.gd</code> → '''Connector''' – area detector system useful in many contexts, including tool couplers and charge stations.
	* <code>bucket_attachment.~~gd</code> → '''Bucket''' – digs into terrain to collect dirtballs~~.
	* <code>~~saw_blade_attachment~~.gd</code> → '''~~SawBlade~~''' – ~~spinning blade for cutting objects~~.
	* <code>dem_loader.gd</code> → '''DemLoader''' – loads fixed DEM heightmaps and extends <code>TerrainStatic256</code>, which is declared via GDExtensions. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].		* <code>dem_loader.gd</code> → '''DemLoader''' – loads fixed DEM heightmaps and extends <code>TerrainStatic256</code>, which is declared via GDExtensions. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].
	~~These classes are referenced throughout the systems described below~~.		* <code>forks.gd</code> → '''Forks''' – tool attachment for moving objects. See [[LUMINSim Documentation#Tools and Attachments\|Tools and Attachments]].
			* <code>saw_blade_attachment.gd</code> → '''SawBlade''' – spinning blade for cutting objects. See [[LUMINSim Documentation#Tools and Attachments\|Tools and Attachments]].
			* <code>tool_attachment.gd</code> → '''ToolAttachment''' – base class for all detachable tools. See [[LUMINSim Documentation#Tools and Attachments\|Tools and Attachments]].
			* <code>ToolCouplerComponent.gd</code> → '''ToolCoupler''' – manages attaching tools to a robot via physics joints. See [[LUMINSim Documentation#Tools and Attachments\|Tools and Attachments]].
	== Autonomy System ==		== Autonomy System ==
	The current autonomous driving logic is implemented by the <code>AutonomyComponent</code> script. Every robot scene instantiates this node under its root <code>VehicleBody3D</code>.		The current autonomous driving logic is implemented by the <code>AutonomyComponent</code> script. Every robot scene instantiates this node under its root <code>VehicleBody3D</code>.
Line 97:		Line 95:

	== Tools and Attachments ==		== 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. <code>tool_spawner.gd</code> respawns tools removed from its bays.		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 [[LUMINSim Documentation#Excavation Tools\|Excavation Tools]] under [[LUMINSim Documentation#Robot Systems\|Robot Systems]]). <code>tool_spawner.gd</code> respawns tools removed from its bays.

	== Robot Systems ==		== Robot Systems ==
Line 104:		Line 102:

	=== Astronaut Character ===		=== Astronaut Character ===
	<code>astronaut_character_3d.gd</code> provides walking and camera control for a procedurally animated astronaut.		<code>astronaut_character_3d.gd</code> provides walking and camera control for a procedurally animated astronaut. We hope to implement VR for the astronaut in the future.

	=== Excavation Tools ===		=== Excavation Tools ===
	Attachments such as the bucket, forks, and saw blade extend '''ToolAttachment''' for various tasks.		Attachments such as the bucket, forks, and saw blade extend '''ToolAttachment''' (see [[LUMINSim Documentation#Classes\|Classes]]) for various tasks. The files for these attachments are currently in [[LUMINSim Documentation#Astra Robot\|Astra]]'s directory, but this is subject to change.

	=== [[Excahauler]] Robot ===		=== [[Excahauler]] Robot ===
	The main scene is <code>excahauler_3d.tscn</code>. Unlike [[LUMINSim Documentation#Astra Robot\|Astra's implementation]], all functionalities are within that <code>.tscn</code> file and the associated <code>.gd</code> file. 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.		The main scene is <code>excahauler_3d.tscn</code>. Unlike [[LUMINSim Documentation#Astra Robot\|Astra's implementation]], all functionalities are within that <code>.tscn</code> file and the associated <code>.gd</code> file. 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 [[LUMINSim Documentation#Major Issues\|Major Issues]]).

	== Objects ==		== Objects ==
Line 116:		Line 114:

	== Static Objects ==		== Static Objects ==
	Charge stations, solar panels, tool spawners, and other environment pieces ~~provide energy or spawn tools~~.		Charge stations and solar panels (see [[LUMINSim Documentation#Power System\|Power System]]), tool spawners, and other generally useful environment pieces. These scenes generally work independently of other scenes, and include:

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

	== Networking and Multiplayer ==		== Networking and Multiplayer ==
Line 125:		Line 127:

	== Cameras and Controls ==		== Cameras and Controls ==
	<code>movable_camera_3d.gd</code> and <code>freecam.gd</code> implement user-controlled cameras~~, both first- and third-person~~.		<code>movable_camera_3d.gd</code> and <code>freecam.gd</code> implement user-controlled cameras.

	== Levels ==		== Levels ==
	Scenes in <code>demo/levels/</code> (e.g., <code>main3D.tscn</code> with script <code>main3D.gd</code>) instantiate players, objects, and the terrain simulator, driving the overall game loop.		Scenes in <code>demo/levels/</code> (e.g., <code>main3D.tscn</code> with script <code>main3D.gd</code>) instantiate players, objects, and the terrain simulator, driving the overall game loop.

	~~== Independent Scenes ==~~
	~~Several standalone scenes provide gameplay utilities:~~
	* <code>brick_maker.gd</code> – creates bricks when filled with loose dirt.
	* <code>tool_spawner.gd</code> – keeps bays stocked by respawning attachments.
	* <code>dirt_spawner.gd</code> – continuously emits dirtballs for terrain testing.

	== Additional Utilities ==		== Additional Utilities ==

Acmattson3 at 02:28, 8 July 2025

2025-07-08T02:28:24Z

← Older revision		Revision as of 18:28, 7 July 2025
Line 2:		Line 2:
	This is an ongoing page as I ([[User:Acmattson3\|Andrew Mattson]]) document [[LUMINSim]]'s current systems. This page is a ''major'' work in progress; feel free to add to it!		This is an ongoing page as I ([[User:Acmattson3\|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:		Going forward, I hope to add in-depth descriptions of the inner workings of each major system, including:
	* A list of the non-default classes/nodes this project declares.		* Power
	* In-depth descriptions of the inner workings of each major system, including:		* Tools and tool swapping
	** Power		* Terrain
	** Tools and tool swapping		* Multiplayer
	** Terrain		* Each user-controlled scene (robots and astronaut)
	** Multiplayer		* The UI (multiplayer menu, settings menu, keybind menu)
	** Each user-controlled scene (robots and astronaut)		* Each (largely) independent scene and corresponding system(s) (brick maker, dirt spawner, tool spawner, etc.)
	** 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 ==		== Getting Started ==
	To learn how to get started with development yourself, [https://github.com/AuroraRoboticsLab/GodotRobot/blob/main/README.md visit the repository's README] and follow the steps there to get the project set up.		To learn how to get started with development yourself, [https://github.com/AuroraRoboticsLab/GodotRobot/blob/main/README.md 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 [[LUMINSim Documentation#Classes\|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 ==		== Repository Structure ==
Line 39:		Line 50:

	== Classes ==		== Classes ==
	The following scripts register custom nodes with `class_name`:		The following scripts register custom nodes with the keyword <code>class_name</code>:
	* <code>ToolCouplerComponent.gd</code> → '''ToolCoupler''' – manages attaching tools to a robot via physics joints.		* <code>ToolCouplerComponent.gd</code> → '''ToolCoupler''' – manages attaching tools to a robot via physics joints.
	* <code>connector_component.gd</code> → '''Connector''' – area detector used by tool couplers and charge stations.		* <code>connector_component.gd</code> → '''Connector''' – area detector used by tool couplers and charge stations.
	* <code>autonomy_component.gd</code> → '''AutonomyComponent''' – simple navigation helper for NPC robots.		* <code>autonomy_component.gd</code> → '''AutonomyComponent''' – simple navigation helper for NPC robots. See [[LUMINSim Documentation#Autonomy System\|Autonomy System]].
	* <code>charge_component.gd</code> → '''ChargeComponent''' – tracks battery state and handles charging/discharging.		* <code>charge_component.gd</code> → '''ChargeComponent''' – tracks battery state and handles charging/discharging.
	* <code>better_hinge_joint_3d.gd</code> → '''BetterHingeJoint3D''' – wrapper over <code>Generic6DOFJoint3D</code> for motorized joints.		* <code>better_hinge_joint_3d.gd</code> → '''BetterHingeJoint3D''' – wrapper over <code>Generic6DOFJoint3D</code> for motorized joints.
Line 49:		Line 60:
	* <code>bucket_attachment.gd</code> → '''Bucket''' – digs into terrain to collect dirtballs.		* <code>bucket_attachment.gd</code> → '''Bucket''' – digs into terrain to collect dirtballs.
	* <code>saw_blade_attachment.gd</code> → '''SawBlade''' – spinning blade for cutting objects.		* <code>saw_blade_attachment.gd</code> → '''SawBlade''' – spinning blade for cutting objects.
	* <code>dem_loader.gd</code> → '''DemLoader''' – loads fixed DEM heightmaps and extends <code>TerrainStatic256</code>.		* <code>dem_loader.gd</code> → '''DemLoader''' – loads fixed DEM heightmaps and extends <code>TerrainStatic256</code>, which is declared via GDExtensions. See [[LUMINSim Documentation#Terrain System (C++)\|Terrain System (C++)]].
	These classes are referenced throughout the systems described below.		These classes are referenced throughout the systems described below.

			== Autonomy System ==
			The current autonomous driving logic is implemented by the <code>AutonomyComponent</code> script. Every robot scene instantiates this node under its root <code>VehicleBody3D</code>.

			Currently, this is how it works:

			* A child <code>NavigationAgent3D</code> computes a path when <code>pathfind_to(target_pos)</code> is called.

			* During <code>_physics_process()</code> the component steers the robot toward the next path point using the <code>get_drive()</code> and <code>get_steer()</code> helpers.

			* The helpers are polled by <code>astra_3d.gd</code> 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 <code>have_arrived</code> flag is set.

			=== Proposed External API ===
			To enable players to program autonomy from outside the engine, a new <code>AutonomyServer</code> 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 <code>AutonomyServer</code> would relay commands to the relevant nodes (mirroring the current <code>get_drive()</code> and <code>get_steer()</code> methods) while still supporting multiplayer authority checks via <code>GameManager</code>.

	== Terrain System (C++) ==		== Terrain System (C++) ==
Line 71:		Line 100:

	== Robot Systems ==		== Robot Systems ==
	=== Astra Robot ===		=== [[Astra]] Robot ===
	The main ~~rover~~ scene is <code>astra_3d.tscn</code>. <code>astra_3d.gd</code> handles driving, energy usage, and tool attachment. It works with <code>astra_arm_3d.gd</code> and <code>astra_hopper_3d.gd</code> ~~for the arm and hopper.~~		The main scene is <code>astra_3d.tscn</code>. <code>astra_3d.gd</code> handles driving, energy usage, and tool attachment. It works with <code>astra_arm_3d.gd</code> and <code>astra_hopper_3d.gd</code> and their associated <code>.tscn</code> files for the robot's arm and hopper.

	~~=== Arm~~ and ~~Hopper ===~~
	~~Separate nodes controlled by~~ <code>~~astra_arm_3d~~.gd</code> and ~~<code>astra_hopper_3d.gd</code> implement joint movement~~.

	=== Astronaut Character ===		=== Astronaut Character ===
Line 83:		Line 109:
	Attachments such as the bucket, forks, and saw blade extend '''ToolAttachment''' for various tasks.		Attachments such as the bucket, forks, and saw blade extend '''ToolAttachment''' for various tasks.

	=== Excahauler Robot ===		=== [[Excahauler]] Robot ===
	~~Work~~ in ~~progress~~.		The main scene is <code>excahauler_3d.tscn</code>. Unlike [[LUMINSim Documentation#Astra Robot\|Astra's implementation]], all functionalities are within that <code>.tscn</code> file and the associated <code>.gd</code> file. 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.

	== Objects ==		== Objects ==