ideal-project-directory-structure.txt

# vrgame — Ideal Project Directory Layout (FINAL v1)
# 3D free-fly camera demo  →  PC+VR hero shooter (AAA stack)
#
# Legend:
#   [OK]   = exists & wired (in this repo today)
#   [TODO] = planned; create as we evolve
#   [OPT]  = optional / later, when ready
#   [GEN]  = generated at build/run time (not committed)

# Design invariants
# - Cross-platform first: Windows + macOS (MoltenVK) + Linux. No “works on my OS” regressions.
# - No relative @imports. All module wiring happens in build.zig.
# - Unit tests live inline at the bottom of Zig source files; tests/ hosts integration/e2e/conformance.
# - src/root.zig is the public engine/game façade; src/main.zig is the desktop demo launcher.
# - Graphics (GLFW + Vulkan + OpenXR) lives under src/graphics and src/client/render.
# - Simulation/gameplay & input are separate from graphics and evolve in parallel.
# - ZDBs are for durable data (players, matches, replays, telemetry) — not per-frame state.
# - Shaders: author in shaders/src (GLSL); build.zig compiles to SPIR-V placed in shaders/ next to the exe.
# - Viewport/Projection Y-parity rule (locked by tests):
#     macOS(MoltenVK): negative viewport height; standard projection.
#     Windows/Linux:   standard viewport; flip projection (negate m[5]).

# Phase milestones
# P0  Camera demo solid on Win/mac/Linux (viewport/projection parity locked by tests).
# P1  Real 3D scene (multi-mesh, transforms, depth, a light), zero 2D leftovers.
# P2  OpenXR desktop VR (instanced stereo, proper swapchain paths, controller input).
# P3  Client/Server split, prediction/reconciliation, bot match demo.
# P4  Replay format + viewer; beginning of hero shooter loop.
# P5  Liveops hooks (ZDBs), anti-cheat signals, matchmaking, telemetry.

# Top-level
vrgame/
|   [OK]  .gitattributes
|   [OK]  .gitignore
|   [OK]  build.zig
|   [OK]  build.zig.zon
|   [OK]  config.json
|   [OK]  ideal-project-directory-structure.txt        # keep truthful as reality changes
|   [OK]  README.md
|   [TODO] .editorconfig                               # Zigadel whitespace/style rules
|   [TODO] .dpignore                                   # for dump_project / vault tooling
|   [OPT]  LICENSE
|   [OPT]  CHANGELOG.md
|   [OPT]  CONTRIBUTING.md
|   [OPT]  SECURITY.md
|   [OPT]  CODEOWNERS
|
+---registry/                                          # registries for generators & tests
|       [OK]  vk.xml
|       [OK]  xr.xml
|
+---shaders/                                           # runtime-loaded SPIR-V blobs (next to exe)
|   [OK]  triangle.vert
|   [OK]  triangle.frag
|   [OK]  basic_lit.vert
|   [OK]  basic_lit.frag
|   +---src/                                           # authoring sources (to add)
|   |       [TODO] triangle.vert.glsl
|   |       [TODO] triangle.frag.glsl
|   |       [TODO] basic_lit.vert.glsl
|   |       [TODO] basic_lit.frag.glsl
|   \---include/
|           [TODO] common.glsl
|
+---assets/                                            # future art/audio/UI sources
|   +---textures/     [TODO]
|   +---models/       [TODO]
|   +---audio/        [TODO]
|   \---ui/           [TODO]
|
+---docs/                                              # architecture and design notes
|       [TODO] ARCHITECTURE.md
|       [TODO] GRAPHICS_STACK.md
|       [TODO] GAMEPLAY.md
|       [TODO] NETCODE.md
|       [TODO] VR.md
|       [TODO] REPLAY.md
|       [TODO] ANTI_CHEAT.md
|       [TODO] MATCHMAKING.md
|       [TODO] PROGRESSION.md
|       [TODO] ZDB_INTEGRATION.md
|       [TODO] LIVEOPS.md
|       [TODO] PERF.md
|
+---configs/
|       [TODO] default.zson
|       [TODO] dev.zson
|       [TODO] staging.zson
|       [TODO] production.zson
|       [OPT]  input_pc.zson
|       [OPT]  input_vr.zson
|       [OPT]  graphics_presets.ztable
|
+---schemas/                                           # game/content/ZDB schemas (ZTable)
|       [TODO] heroes.ztable
|       [TODO] abilities.ztable
|       [TODO] maps.ztable
|       [TODO] modes.ztable
|       [TODO] matchmaking.ztable
|       [TODO] progression.ztable
|       [TODO] cosmetics.ztable
|       [TODO] telemetry_signals.ztable
|       [TODO] anti_cheat_signals.ztable
|
+---zdb/                                               # non-primitive game DBs (file/cluster modes)
|   +---ZPlayerDB/     [TODO] README.md  config.zson
|   +---ZMatchDB/      [TODO] README.md  config.zson
|   +---ZReplayDB/     [TODO] README.md  config.zson
|   +---ZTelemetryDB/  [TODO] README.md  config.zson
|   \---ZAntiCheatDB/  [TODO] README.md  config.zson
|
+---deploy/
|   +---docker/        [TODO] Dockerfile.client  Dockerfile.server
|   +---hydra/         [TODO] game_server.zson  matchmaker.zson  replay_worker.zson  anticheat_worker.zson
|   \---zap/           [TODO] zap_routes.zson
|
+---examples/                                          # tiny demos built on the real engine
|   +---01-local-sandbox/   [TODO] README.md  src/main.zig
|   +---02-bot-match/       [TODO] README.md  src/main.zig
|   \---03-replay-viewer/   [TODO] README.md  src/main.zig
|
+---src/
|   [OK]  main.zig                                     # desktop demo entry (GLFW + Vulkan)
|   [OK]  root.zig                                     # public façade; wraps engine/client/server/tools
|   |
|   +---math/
|   |       [OK]  math3d.zig                           # Vec3/Mat4, projections, camera math
|   |       [TODO] geom.zig                            # AABB, frustum, intersections
|   |
|   +---game/
|   |       [OK]  camera3d.zig                         # FPS-style Camera3D + CameraInput
|   |       [OK]  frame_time.zig                       # FrameTimer
|   |       [OK]  game.zig                             # legacy 2D sample (reference only)
|   |
|   +---graphics/
|   |       [OK]  graphics_context.zig                 # Vk instance/device/queues/surface/allocator
|   |       [OK]  swapchain.zig                        # swapchain + resize-safe recreation & sync
|   |       [OK]  vertex.zig                           # vertex format + binding/attribute descs
|   |       [OK]  depth.zig                            # depth format choice + image/view helpers
|   |       [OK]  texture.zig                          # (stub/early) texture helpers
|   |       [OK]  mesh.zig                             # (stub/early) mesh helpers
|   |   \---camera/                                    # legacy math camera stack (reference)
|   |           [OK]  camera.zig
|   |           [OK]  projection.zig
|   |           [OK]  transform.zig
|   |           [OK]  vector.zig
|   |           [OK]  view.zig
|   |
|   +---engine/        # simulation core (future)
|   |   +---core/      [TODO] math.zig rng.zig time.zig world.zig physics.zig nav.zig movement.zig damage.zig status.zig projectiles.zig
|   |   +---lagrangian/[TODO] base.zig ability.zig
|   |   +---animation/ [TODO] skeleton.zig pose.zig ik.zig anim_graph.zig
|   |   +---biomech/   [TODO] rig.zig muscle.zig controller.zig contact.zig
|   |   +---audio/     [TODO] mixer.zig spatial.zig events.zig
|   |   +---vfx/       [TODO] system.zig events.zig
|   |   +---camera/    [TODO] pc_camera.zig vr_camera.zig spectator.zig
|   |   +---replay/    [TODO] recorder.zig player.zig highlight.zig
|   |   \---anti_cheat/[TODO] signals.zig detector.zig review.zig
|   |
|   +---gameplay/
|   |   +---heroes/    [TODO] catalog.zig hero_skyline.zig hero_cascade.zig hero_bastion_guard.zig hero_rupture_gauntlet.zig
|   |   +---abilities/ [TODO] ability_defs.zig ability_air_slash.zig ability_ice_ramp.zig ability_tidal_heal.zig ability_shield_break.zig ability_meteor_fist.zig
|   |   +---maps/      [TODO] map_catalog.zig script_city_rooftops.zig script_canal_plaza.zig script_foundry_crossing.zig
|   |   +---modes/     [TODO] mode_payload.zig mode_control_point.zig mode_hybrid.zig
|   |   +---progression/[TODO] xp.zig unlocks.zig
|   |   \---economy/   [TODO] currencies.zig store.zig
|   |
|   +---net/
|   |       [TODO] protocol.zig snapshot.zig prediction.zig lag_comp.zig
|   |
|   +---client/
|   |   [TODO] app.zig loop.zig
|   |   +---input/     [TODO] pc.zig vr.zig accessibility.zig
|   |   +---render/    [TODO] vulkan_device.zig vulkan_renderer.zig openxr_session.zig glfw_window.zig post_process.zig debug_draw.zig
|   |   \---ui/        [TODO] hud.zig menus.zig scoreboard.zig social.zig
|   |
|   +---server/
|   |   [TODO] app.zig loop.zig
|   |   +---auth/      [TODO] sessions.zig
|   |   +---match/     [TODO] session.zig rules.zig matchmaking.zig
|   |   +---bots/      [TODO] ai_controller.zig behavior.zig
|   |   +---net/       [TODO] listener.zig client_conn.zig
|   |   \---zdb_hooks/ [TODO] player_sync.zig match_log.zig replay_export.zig telemetry_export.zig anticheat_export.zig
|   |
|   \---lib/
|           [TODO] bitset.zig pool.zig ring_buffer.zig string_pool.zig
|           [OPT]  logger.zig
|
+---tests/                                             # higher-level tests; unit tests live inline
|   [OK]  test_all_conformance.zig
|   [OK]  test_all_e2e.zig
|   [OK]  test_all_integration.zig
|   [OK]  _support.zig
|   +---conformance/
|   |       [OK]  pipeline_defaults.zig
|   |       [TODO] test_config_conformance.zig
|   |       [TODO] test_schema_conformance.zig
|   |       [TODO] test_protocol_conformance.zig
|   |       [TODO] test_zdb_integration_conformance.zig
|   +---integration/
|   |       [OK]  camera3d_exports.zig
|   |       [OK]  camera3d_public_decls.zig
|   |       [OK]  frame_time_exports.zig
|   |       [OK]  frame_time_public_decls.zig
|   |       [OK]  frame_timer_window.zig
|   |       [OK]  glfw_exports.zig
|   |       [OK]  glfw_vulkan_headers_sanity.zig
|   |       [OK]  glsl_sources_present.zig
|   |       [OK]  graphics_context_exports.zig
|   |       [OK]  graphics_context_public_decls.zig
|   |       [OK]  math3d_lookat_orthonormal.zig
|   |       [OK]  math3d_mul_props.zig
|   |       [OK]  math3d_perspective_basic.zig
|   |       [OK]  math3d_projection_props.zig
|   |       [OK]  math3d_sanity.zig
|   |       [OK]  math3d_viewproj_center_ndc.zig
|   |       [OK]  repo_layout_sanity.zig
|   |       [OK]  shader_sources_exist.zig
|   |       [OK]  shaders_exist.zig
|   |       [OK]  swapchain_public_decls.zig
|   |       [OK]  types_size_sanity.zig
|   |       [OK]  vertex_contract.zig
|   |       [OK]  vertex_layout.zig
|   |       [OK]  vk_headers_sanity.zig
|   |       [OK]  vk_structs_compile.zig
|   |       [OK]  xr_headers_sanity.zig
|   |       [OK]  xr_registry_exists.zig
|   |       [OK]  viewport_projection_y_parity.zig
|   \---e2e/
|           [OK]  smoke_cli_build.zig
|           [TODO] test_local_sandbox_cli.zig
|           [TODO] test_dedicated_server_cli.zig
|           [TODO] test_match_flow_e2e.zig
|           [TODO] test_liveops_config_rollout.zig
|
+---tools/
|   +---bench/       [TODO] core_physics.zig net_pipeline.zig lagrangian.zig biomech.zig bench_all.zig
|   +---dev/         [TODO] hero_editor.zig map_editor.zig replay_tools.zig telemetry_inspector.zig
|   \---scripts/     [TODO] fmt.sh dev.ps1 build_assets.sh release_notes_from_git.sh
|
+---third_party/
|   [OPT]  glfw/     # only if vendoring C sources instead of Zon deps
|   [OPT]  imgui/
|   [OPT]  audio_backend/
|
\---ci/
        [OPT]  github-actions.yml                      # matrix (Win/mac/Linux), zig 0.16 nightly, shader build smoke
        [OPT]  precommit.sh

# Build & run cheatsheet
#   zig build test-all --summary all
#   zig build run
#
# Cross-platform Y-parity rule (locked by tests):
#   macOS (MoltenVK):   negative viewport height, keep standard projection.
#   Windows/Linux:      standard viewport, flip projection by negating m[5].