# ASTRA Mission Studio
## Player Reference & Instruction Manual

### 1. Title & Introduction

Design a spacecraft for a science mission, then watch it fly in ASTRA’s 3D mission simulator. Choose a destination, balance the spacecraft’s resources, and see how your engineering decisions shape the mission report.

There is no conventional win-or-lose screen: each flight earns a mission score and a debrief. Aim for a high score while meeting the mission’s budget, payload-mass, and power constraints; redesign and fly again to improve the result.

### 2. System Requirements & Setup

ASTRA is a browser-based game made with HTML, CSS, and JavaScript. The mission-planning interface uses Three.js for its 3D previews, and the flight simulator loads a 3D spacecraft model.

#### Requirements

- A current desktop browser with JavaScript and WebGL enabled
- Internet access to load the Three.js and interface libraries from their CDNs
- The game’s `assets` folder kept alongside the HTML files
- Browser storage enabled to save mission and audio settings

#### Recommended setup

1. Open the project folder in VS Code (or any editor).
2. Serve the folder with a local web server (required for modules, WebGL assets, and the embedded flight simulator). Examples:
   - VS Code Live Server extension → open `index.html`
   - Python: `python -m http.server 8080` then visit `http://localhost:8080`
   - Node: `npx serve .`
3. Wait for mission control to finish loading.
4. Choose a destination and configure the mission, or resume the saved workspace.

**Entry point:** `index.html` (this is the main Mission Studio).  
The flight simulator is loaded from `raza-flight-sim.html` inside an iframe.  
Keep the `assets/` folder next to the HTML files. The project does not require a separate install or account.

### 3. Controls & Mechanics

#### Controls

| Input | Action |
|---|---|
| Mouse drag on the 3D view | Rotate the camera around the spacecraft |
| Mouse wheel / trackpad scroll over the 3D view | Zoom the camera |
| **Reset View** | Return the camera to its default view |
| **Follow Ship** | Center the camera on the spacecraft during flight |
| **On Ship · Cockpit** | Switch to the cockpit camera |
| Throttle slider | Set flight throttle from 0% to 100% |
| **Ⅱ Pause / Resume** | Pause or resume the flight |
| **RESET** | Reset the current flight simulation |
| **Enter full screen** | Expand the simulation; press the button again or use the browser’s full-screen exit control to leave |
| On-screen buttons and selectors | Choose missions, configure the spacecraft, navigate stages, and start tests |

The planner itself has no required keyboard controls. The 3D view uses mouse and touch gestures supported by the browser.

#### Mission setup

Choose one of four science scenarios:

- **Launch the space shuttle** — check a payload and spacecraft systems in low Earth orbit
- **Lunar south-pole mapper** — map shadowed craters and scout landing terrain
- **Mars water scout** — search for buried water ice and mineral clues
- **Europa ice listener** — study the icy shell and magnetic field

Select a challenge level (Guided, Standard, or Expert), and optionally assign up to four planning participants names and roles. Then configure the spacecraft bus, power system, communications, launch vehicle, orbit, and science instruments.

#### Flight and scoring

- The flight progresses through lift-off and ascent, system checks, orbit insertion, science operations, and data return.
- The simulator’s throttle affects how quickly the flight progresses. At 0%, flight progress stops; increase the throttle to continue.
- Mission duration depends on the selected scenario and throttle.
- The report gives a score from 0 to 100. It reflects science fit and engineering trade-offs, including power, communications/data return, mass, budget, orbit suitability, and challenge level.
- The report highlights constraints and design findings. Budget, launch-mass, and power overruns are treated as critical resource constraints; data-return limits and orbit fit are also reported.
- Mission designs and audio preferences are saved in the current browser profile. Use **Save mission** to save the workspace.

### 4. Gameplay Guide

1. **Choose a mission.** Select the destination and challenge level on the Mission brief screen. Set the planning team and roles if desired.
2. **Design the spacecraft.** Select an orbit, spacecraft bus, power system, communications system, launch vehicle, and science instruments. Watch the resource board for cost, mass, power, and other trade-offs.
3. **Review constraints.** Check the live findings before continuing. A design may still fly with problems, but the debrief will identify them and the score may suffer.
4. **Run the flight test.** Select **Run flight test**, wait for the simulator to load, then select **Launch mission**. Use the camera controls and throttle while the flight runs.
5. **Pause or reset if needed.** Use the simulator’s pause control to hold the flight. **RESET** starts the current test over; **Revise spacecraft** returns to the design stage.
6. **Read the debrief.** When the flight completes, open **View mission report** to see the score, resource findings, and science return.
7. **Iterate.** Choose **Improve design** or return to spacecraft design, adjust the configuration, and run another test. Use **Run simulation again** to repeat the flight with the current design.

The **Save mission** button stores the current plan in this browser. **Share mission** copies a link containing the mission configuration; anyone opening it must also be able to access the same game page URL.

### 5. Advanced Strategy & Tips

1. **Check the full resource picture.** Instruments add science value but also increase mass, power demand, data volume, and cost. A strong payload is one the spacecraft can actually support.
2. **Match the orbit to the destination.** The planner identifies target-compatible orbits and flags a less direct fit. Choose an orbit that supports the mission’s science objective.
3. **Keep engineering margin.** Avoid designing exactly at the launch vehicle’s mass limit or the power system’s capacity. Extra margin makes it easier to accommodate useful instruments without triggering a critical constraint.
4. **Treat communications as part of the payload plan.** Compare generated science data with the selected radio’s return capacity. Reduce data-heavy instruments or improve communications if the report shows a backlog.
5. **Use flight time productively.** The throttle slider controls how quickly the simulation advances. Lower it to watch the sequence more slowly; raise it to complete the flight sooner.

### Quick Reference

- **Goal:** Build a science mission with a strong score and manageable engineering constraints.
- **Flow:** Brief → Spacecraft design → Flight test → Mission report.
- **During flight:** Adjust throttle, change camera view, pause, or reset.
- **After flight:** Review findings, revise the design, and rerun.
- **Saved data:** Mission workspace and audio preferences are stored in browser local storage.
