| # Repoverse 3D district |
|
|
| The C# world generator now has an authenticated, loopback-only HTTP sidecar and |
| an Unreal client in the existing Repoverse module. The original 2D GameMode |
| remains the default; the 3D launcher selects RepoverseWorldMode explicitly. |
|
|
| ## Build and run |
|
|
| Requires .NET 8 SDK, Unreal Engine 5.4 or newer, and the matching Visual Studio |
| C++ toolchain. From the repository root in PowerShell: |
|
|
| ./tools/Start-Repoverse3D.ps1 -EngineRoot 'D:/Epic/UE_5.6' |
| |
| Use your actual installation path. This example is not an installed-engine claim. |
| The script ingests this Git checkout, creates the authoritative manifest, builds |
| Unify and the Unreal host, starts a local sidecar with a fresh session token, |
| waits for its health endpoint, and launches the 3D GameMode. On editor exit it |
| stops only the sidecar process it started. Logs and the save are in out/world3d. |
| Use -SourceRoot to explore another local Git checkout, or -SkipBuild after a |
| successful build. The default launcher creates a world for one repository; |
| multiple buildings can be served from an existing multi-repository manifest. |
|
|
| ## Controls implemented in the Unreal client |
|
|
| - WASD/arrows move, mouse looks, Space jumps, Shift runs. |
| - Near a ladder, hold Space to climb or Ctrl to descend. |
| - E inspects a nearby source terminal. PgUp/PgDn page source; Esc closes it. |
| - Tab/Shift+Tab travel between manifest repositories. |
| - 1 returns to walking, 2 orbits the selected destination, 3 opens its overview. |
| - F5 saves, F9 restores. Esc outside source view saves successfully before quitting. |
|
|
| Movement waits for nearby terrain to load. Meshes and collision use the same |
| C# greedy quads. The coordinate conversion is centralized: one voxel is 50 cm, |
| core (x,y,z) becomes Unreal (x,z,y), and triangle winding reverses once. |
| Ladder mesh sections do not collide. Materials are generated by create-map.py; |
| no new artwork is required. Windows currently use an opaque blue material. |
|
|
| ## Service contract, version 1 |
|
|
| All requests require X-Repoverse-Token. The service binds 127.0.0.1 only and |
| rejects Origin-bearing requests. A single renderer owns a service session; |
| requests execute serially. This is not a multiplayer server. |
|
|
| | Route | Behavior | |
| | --- | --- | |
| | POST /v1/session | Reset renderer residency; return player, destinations and artifact objects | |
| | POST /v1/focus | Accept x/z in core units; return at most four chunk meshes plus unload IDs | |
| | POST /v1/save | Accept PlayerState; atomically save player and voxel edits | |
| | POST /v1/load | Restore matching world snapshot; invalidate resident meshes | |
| | POST /v1/edit | Apply a packed voxel edit and invalidate neighboring faces | |
| | GET /v1/source | Read 32 lines of a manifest artifact from the explicitly mapped local checkout | |
| | GET /v1/health | Report protocol version and resident chunk count | |
|
|
| The stream radius is one chunk with one chunk of unload hysteresis. Source reads |
| are capped at 2 MiB, reject links/path traversal, and never execute repository |
| code. Local source contents reflect the current working copy, not a historical |
| Git blob. Other repositories require their own source mapping; remote source |
| fetching is not implemented. Save restoration rejects a different world seed, |
| generator, or snapshot. API edits are available; an in-game build tool is not. |
|
|
| ## Verification and remaining work |
|
|
| The C# solution builds with warnings as errors. Unit tests cover bounded |
| residency, unload/reload, edit persistence, boundary remeshing, outward triangle |
| winding, passable ladders, source paging and source restrictions. Run: |
|
|
| dotnet test Repoverse.sln |
| python tools/test-sidecar.py |
| |
| The second command runs a real sidecar process against a manifest generated |
| from this checkout, including auth, HTTP streaming, save/load and source reads. |
|
|
| **The new Unreal client has not been compiled or played in Unreal.** An Unreal |
| installation was not found in this session. This is an integration awaiting |
| engine validation, not a finished or packaged 3D game. Required editor checks: |
| compile with UBT; walk into the building; collide with walls; climb all floors; |
| inspect a file; orbit; travel; save; quit; restart and restore; disconnect the |
| service; exit PIE. Measure frame time and mesh/collision upload costs. |
|
|
| Remaining beyond this vertical slice: rendered dependency graph, architectural |
| roof/floor cutaways, remote source retrieval, multi-repository source mappings, |
| search/bookmarks, live synchronization, complete camera persistence, transparent |
| windows, CAD, Swift control plane, and the absent Parts II/III directive. |
|
|
| ## Twin-O-Matic builder |
|
|
| Export a build from the matching Twin-O-Matic browser app, then pass its JSON path to the launcher with `-BuildPlan`. The launcher sends the plan to authenticated `POST /v1/build` before opening Unreal. This leaves browser-origin requests blocked. No generated script is executed. |
|
|
| Version 1 plans carry `id`, `actor`, `units: "voxel"`, integer `origin` (Y-up), and `operations` with shape names and arguments. Boxes, spheres, cylinders, cones and XY-plane tori are supported. The entire plan is validated/rasterized before edits apply. Limits: 128 operations, 262144 candidate samples, 32768 resulting voxels, 16 builder identities per world. Smaller-than-voxel features may vanish; colors quantize to existing material families. Lights/particles are preview-only. Imported blocks can replace existing terrain, so select an empty construction area using the plan origin. |
|
|
| The builder body follows its latest completed build position; this is a representation of accepted build commands, not an autonomous Unreal-hosted language model. F5 stores builder identity and edits; F9 and reconnect restore them. Existing schema-2 saves default to no builders. |
|
|
| Verification: 88 C# tests, real local HTTP build/save/load/reconnect, and a build downloaded by the Twin browser test and submitted to this service. Unreal client changes still require compilation and a real playtest with an installed engine and the user's supplied assets. |
|
|
