Getting Started

This section walks you through installing Darksun, preparing assets, and taking your first tour of the simulation environment.

1. Install & Update

1. Clone the repository

   git clone https://github.com/joaomontenegro/Darksun.git
   cd Darksun

2. Install dependencies using your preferred package manager (PNPM is recommended and required for the docs tooling).

   pnpm install

3. Prepare runtime assets. The default pnpm install step pulls in all front-end and worker dependencies. If you intend to run the physics workers locally, make sure you have the optional data packs (orbital ephemeris, spacecraft models) described in the repository README.

Tip: You can always update to the latest version by pulling the repository and rerunning pnpm install.

2. Launch the App

pnpm dev

This script:

• Generates the spacecraft manifest.
• Starts the Vite development server (default port 5173).
• Watches the physics workers and UI for hot-module replacement.

Open http://localhost:5173 in your browser. You should see the default solar system view once the Three.js scene initialises.

3. Navigate the Interface

1. Top Bar
   • Use the Docs button to open these guides in a separate tab.
   • Toggle the Timeline, Missions, and Copilot windows with the respective buttons.
2. Window Manager
   • Drag any window by its title bar.
   • Resize using the edges (the pointer cursor will change).
   • Close and reopen windows from the top bar buttons as needed.
3. 3D Scene
   • Orbit around: right-click drag.
   • Pan: middle-click drag.
   • Zoom: mouse wheel.

4. Create a Spacecraft

1. Open the Spacecraft window from the top bar.
2. Click + New Spacecraft to launch the wizard.
3. Adjust the default orbital or geodetic parameters (the provided values create a ~400 km Earth orbit) and tweak the stage presets if required.
4. Select the spacecraft in the list and use the Info button to open its detail window, or Focus to centre the camera on it.

5. Run a Simple Manoeuvre

1. Open the Planner window.
2. Pick your spacecraft from the drop-down at the top.
3. Replace the help text with a single line, for example:

   +10m [0.050,0,0]

   This schedules a 50 m/s prograde burn ten minutes from now.
4. Click Run Maneuver Program. The planner builds the manoeuvre node and the physics worker executes it at the scheduled time.

6. Configure the Simulation Clock

• Play/Pause using the controls in the bottom bar.
• Adjust time warp with the control in the bottom bar (use the popover to enter an exact value).
• The current epoch is displayed in UTC; click it to jump to a specific timestamp.

7. Enable the Copilot (Optional)

If you have the AI copilot key configured:

1. Open the Copilot window.
2. Connect using your Stack Auth account credentials.
3. Ask a question such as “Summarise the current mission plan.” The Copilot replies using live data from the planner.

Troubleshooting

Issue	Resolution
Blank Three.js canvas	Wait for assets to finish loading or check the browser console for shader compilation errors.
Physics workers not responding	Ensure your browser allows SharedArrayBuffer (usually requires localhost with HTTPS disabled and cross-origin isolation headers handled by Vite).
Docs button opens a placeholder URL	Set VITE_DOCS_URL=http://localhost:3001 in .env.local and run pnpm docs:dev in a separate terminal.

You are now ready to explore the interface guides and delve deeper into simulation specifics. Continue to the Interface Overview next.