Immersive training for AP CSP Unit 4 (Computer Systems and Networks), built in Godot 4.7.2 for the Meta Quest: students build a computer, then a network, and each mission's score is saved to the team's Flask backend (Open-Coding-Society/ocs_backend).
The work follows the team build plan (OCSVR_Training_Plan.md section 5 in the team Drive): laptop first, then the Quest.
New to the project? Start with SETUP.md: installing Godot, cloning, playing, running the checks, and (optionally) the backend and the progress page.
- Install Godot 4.7.2 standard (not .NET). Setup guides with the exact versions are in the team Drive:
OCSVR_Godot_Setup_Windows.mdandOCSVR_Godot_Setup_macOS.md. - Clone this repo and open
project.godotfrom Godot's project manager (Import). - Press Play (F5). Module 1 starts with the "Install the RAM" practice mission, and each finished mission opens the next one after 6 seconds. To play one mission on its own, open its scene and press F6.
| Build-plan step | State |
|---|---|
| 1. Laptop workbench + one snap task | Done: drag the RAM stick into the RAM slot with the mouse |
| 2. One full mission ("Identify components") with hints and a success panel | Done: CPU, RAM, SSD and keyboard into their places, checklist and hints on a 3D panel, score/time/attempts on success |
4. TrainingManager autoload + module registry |
Done: missions are data in data/modules.json; one generic mission script |
| Module 1 missions | All 5, plus a practice: Install the RAM (practice), Identify the components, Assemble the system, Execute a task, Add processing capacity, Diagnose a failure |
| 5. Send scores to Flask | Done: each finished mission is saved through the training API (sign in, start a session, complete it with retries) |
| OpenXR, Quest export preset, vendors plugin | Being set up by Aryan's side; they get added here |
| File | Job |
|---|---|
scenes/room.tscn |
The room every mission uses: light, floor, table, standing camera, grab layer (scripts/room.gd) |
scenes/build_computer/identify_components.tscn |
Module 1, mission 1: a motherboard with CPU socket, RAM slot and M.2 slot, a USB spot for the keyboard, the four parts, and the info panel |
data/modules.json |
The module registry: every module and mission, with its scene, intro and success text, scoring, and each part's and slot's type, name and hint |
scripts/module_registry.gd |
Reads and checks the registry; a typo is reported with the field that's wrong |
scripts/training_manager.gd |
The TrainingManager autoload: Intro → Active (first grab starts the clock) → Success; mistakes, score, attempts; emits module_completed(module_id, score, duration_s) |
scripts/net/score_reporter.gd |
The ScoreReporter autoload: on mission_started it starts a server session; on module_completed it completes it with score, time, attempts and device, retrying if the server can't be reached. Practice missions aren't sent |
scripts/net/training_api.gd |
The HTTP client for the backend's /api/authenticate, /api/sessions/start, /api/sessions/complete and /api/learners/<uid>/progress. Sends the login JWT as Authorization: Bearer |
scripts/missions/mission.gd |
The one script every mission scene uses: gives the scene's parts and slots their registry data and drives the panel |
scripts/ui/info_panel.gd |
A 3D panel (SubViewport on a quad) for intros, checklists, hints and results |
scenes/build_computer/assemble_system.tscn |
Module 1, mission 3: mount the motherboard, PSU and SSD in a case, power last |
scenes/build_computer/execute_task.tscn |
Module 1, mission 4: carry a photo file from the SSD to RAM, the CPU, then the screen |
scenes/build_computer/add_capacity.tscn |
Module 1, mission 5 (advanced): install a GPU, then send step-by-step jobs to the CPU and parallel jobs to the GPU |
scenes/build_computer/diagnose_failure.tscn |
Module 1, mission 6 (advanced): read the symptoms, find the broken RAM, then the dead SSD, and swap in spares |
scenes/workbench.tscn |
The "Install the RAM" practice mission (step 1's workbench, now registry-only) |
scripts/grabbable_part.gd |
A part you can pick up. Knows its part_type; on a drop it picks the one slot that judges it (so a keyboard over three slots is one mistake, not three); goes home if not installed |
scripts/snap_zone.gd |
A slot (Area3D) with a hint. It judges a dropped part: right type → installs it and emits snapped; wrong type → emits rejected |
scripts/input/mouse_grabber.gd |
The laptop's grab/drop layer: press, carry, release. The only script that knows about the mouse |
tests/run_tests.gd |
Headless checks (below) |
The VR rules from the build plan, and where they show up:
- Real scale, 1 unit = 1 m. The RAM stick is 0.133 m long; the table top is 0.9 m high.
- Standing player. The camera is at 1.6 m eye height. Both numbers get replaced by the step 0 headset measurements.
- 3D, not 2D. Every part is a 3D object.
- UI on 3D panels. The mission panel is a SubViewport drawn on a quad, tilted toward the player; part names are
Label3Ds. NoCanvasLayerUI, since it doesn't show in the headset. - One input layer. Parts and SnapZones only see
grab()anddrop(). A controller or hand grabber replacesMouseGrabberwithout touching the game. - No camera moving on its own. The camera is placed once.
- Model setup. Each part is a body with logic and a simple collision shape, with its model as a child named
Mesh. The real models live inmodels/<part>/;tools/fit_models.gdscales each to real size and writesmodels/<part>/<part>_visual.tscn, which the scenes use. Most models are CC BY 4.0, so anyone who adds or swaps a model updates CREDITS.md. - Origin at the snap point. The RAM stick's origin is its bottom edge, and each SnapZone has a
SnapPointmarker.
The game sends results to the team's Flask backend (Open-Coding-Society/ocs_backend), and they show up in GET /api/learners/<uid>/progress and on the pages site's /vr/progress/. Point it at a server and an activated account, either with environment variables:
OCSVR_API_URL=http://localhost:8587 OCSVR_UID=hop OCSVR_PASSWORD=... godot --path .or with a file that stays on your computer, user://ocsvr_api.cfg (on a Mac, ~/Library/Application Support/Godot/app_userdata/OCSVR/ocsvr_api.cfg):
[api]
base_url="http://localhost:8587"
uid="hop"
password="..."Never commit a password. With no account set up, the game still plays, and the success panel says the score wasn't saved. On the Quest, adb reverse tcp:8587 tcp:8587 makes the headset's localhost:8587 reach the laptop's backend.
-
Make a scene: instance
scenes/room.tscn, addInfoPanel(scripts/ui/info_panel.gd), and place your parts (scripts/grabbable_part.gd, aMeshchild and a collision shape, origin at the snap point) and slots (scripts/snap_zone.gd, anArea3Dwith a collision shape and aSnapPointmarker). -
Put
scripts/missions/mission.gdon the scene's root and setmission_idtomodule.mission. -
Add the mission to
data/modules.json: its scene,intro,success,scoring, and every part (type,name) and slot (accepts,name,hint) by node path. Slots can also have:role: what the part does, shown when it's installedrequires: other slots that must be filled first (a part dropped too early is a mistake, and the panel says what comes first)pass_through: true: the part is placed here but stays free to move on, so it can go through several stages, like data moving through the computercapacity: how many parts fill it (a job queue); they sit side by side along the SnapPoint's x axisworking: true: a part that isn't broken. It takes nothing (so noaccepts), isn't on the checklist, and turns any part away with its hint
A zone with a child node named
Replaced(the old part's mesh) hides it once the zone is full.Missions play in the order they're listed.
No new code is needed. If the registry and the scene disagree (a slot in one but not the other, a slot that accepts a type no part has), the game prints exactly what's wrong when it loads.
From the repo folder, with godot meaning your Godot 4.7.2 binary:
godot --headless --import
godot --headless --script res://tests/run_tests.gd # game: snap rules, missions, registry
godot --headless --script res://tests/run_api_tests.gd # score saving, against a fake serverLook for ALL PASSED at the end. Godot exits with 0 even if a test script fails to load, so the exit code alone isn't enough.
With the backend running, tests/run_live_api_test.gd does one real round trip (set the three OCSVR_ variables above; without them it prints SKIPPED). It creates real sessions for that account.
They check the registry (it loads, and bad data is caught with a clear message), the TrainingManager's states and scoring, the snap rules, and both missions played through the real mouse grabber and camera. For example: a perfect run scores 100 with the right time, wrong drops show the slot's hint and cost points, a big part over several slots counts once, and changing per_mistake in the registry changes the score with no code change. Exit code 0 means all passed. A few ERROR lines are expected: they come from tests that feed in bad data on purpose.
- Work on a branch and open a pull request into
main; Aryan merges. - Keep Godot at 4.7.2 so
project.godotand the scene files don't churn between versions. .godot/,/android/andbuild/are ignored: every computer makes its own.