docs: community mapmaking documentation (7-file SDK guide)

- docs/mapmaking/00-index.md — SDK overview with workflow diagram - docs/mapmaking/01-getting-started.md — template setup & first map - docs/mapmaking/02-building-geometry.md — CSG guide & prefab reference - docs/mapmaking/03-lighting-and-env.md — LightmapGI baking guide - docs/mapmaking/04-validation.md — validator CLI & CI/CD usage - docs/mapmaking/05-packaging-and-shipping.md — .pck pipeline - docs/mapmaking/06-faq-and-troubleshooting.md — 30+ common issues - README.md — add mapmaking SDK link to features list
2026-07-01 18:46:10 -04:00
parent 159c554a86
commit 34507f9043
8 changed files with 1382 additions and 1 deletions
@@ -0,0 +1,104 @@
+# Tactical Shooter — Mapmaking SDK
+
+Everything you need to build, validate, package, and ship competitive maps for
+Tactical Shooter. This SDK is designed for the community — no C++, no GDextension
+tinkering required. You only need Godot 4 (any 4.x) and a text editor.
+
+## Quick Start
+
+```bash
+# Copy the template project
+cp -r client/map_template/ maps/my_first_map/
+
+# Rename the demo scene
+mv maps/my_first_map/template_map.tscn maps/my_first_map/de_my_map.tscn
+
+# Open in Godot
+godot maps/my_first_map/project.godot
+```
+
+Then read the [Getting Started guide](01-getting-started.md).
+
+## What You Can Build
+
+- **Competitive defuse maps** — A-site, B-site, CT/T spawns, buy zones
+- **Custom game modes** — The template is gameplay-agnostic; your map logic
+  is in Godot groups, not hardcoded
+- **Community servers** — Ship maps as `.pck` files via the registry server
+
+## SDK Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| [Template project](01-getting-started.md) | `client/map_template/` | Standalone Godot project with CSG prefabs and demo scene |
+| [CSG Prefabs](02-building-geometry.md) | `client/map_template/assets/prefabs/` | 6 drop-in node types (spawns, sites, zones) |
+| [Editor Validator](04-validation.md) | `client/map_template/template_map.gd` | Auto-runs when scene opened in editor |
+| [Headless Validator](04-validation.md) | `client/tools/validate_map.gd` | 4-module CLI validator for CI/CD |
+| [Packaging](05-packaging-and-shipping.md) | `scripts/map_packaging/pack_map.gd` | Exports `.tscn` → `.pck` addon pack |
+| [Registry Server](05-packaging-and-shipping.md) | `scripts/map_packaging/map_registry_server.py` | Serves `.pck` files over HTTP |
+| [Client Downloader](05-packaging-and-shipping.md) | `client/scripts/map_downloader.gd` | Autoload that downloads + loads `.pck` at runtime |
+
+## Map Authoring Workflow
+
+```
+┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
+│ 1. Build         │ ──→ │ 2. Validate       │ ──→ │ 3. Package       │
+│ - CSG geometry   │     │ - Editor check    │     │ - pack_map.gd    │
+│ - Prefab nodes   │     │ - CLI validator   │     │ - → .pck file    │
+│ - Lighting       │     │ - Fix warnings    │     │                   │
+└──────────────────┘     └──────────────────┘     └──────────────────┘
+                                                          │
+                                                          ▼
+┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
+│ 6. Load & Play   │ ←── │ 5. Download       │ ←── │ 4. Upload        │
+│ - Auto-download  │     │ - Registry HTTP   │     │ - map_registry   │
+│ - changelevel    │     │ - Cache to disk   │     │ - .pck + .json  │
+└──────────────────┘     └──────────────────┘     └──────────────────┘
+```
+
+## Performance Targets
+
+Maps built with the SDK must meet these budgets:
+
+| Metric           | Target      | Enforced by                    |
+|------------------|-------------|--------------------------------|
+| Triangle count   | ≤ 50,000    | `validate_polycount.gd`        |
+| Texture size     | ≤ 1024×1024 | `validate_textures.gd`         |
+| Dynamic lights   | ≤ 4         | `validate_lights.gd`           |
+| LightmapGI     | ✓ Baked     | `validate_lights.gd`           |
+| ReflectionProbe | ≥ 1         | `validate_lights.gd` (warning) |
+| FPS target       | 60+         | Project rendering settings     |
+
+## File Structure Reference
+
+```
+tactical-shooter/
+├── client/
+│   ├── project.godot               # Main game project
+│   ├── map_template/               # ← YOU ARE HERE (template project)
+│   │   ├── project.godot           #   Standalone Godot project
+│   │   ├── template_map.tscn       #   Demo scene (rename me)
+│   │   ├── template_map.gd         #   Editor validation script
+│   │   └── assets/prefabs/         #   CSG prefab nodes
+│   ├── tools/
+│   │   ├── validate_map.gd         #   CLI validator entry point
+│   │   └── validate_map/           #   4 validator modules
+│   │       ├── validate_scene.gd
+│   │       ├── validate_polycount.gd
+│   │       ├── validate_textures.gd
+│   │       └── validate_lights.gd
+│   └── scripts/
+│       └── map_downloader.gd       #   Client autoload for .pck loading
+├── scripts/
+│   └── map_packaging/
+│       ├── pack_map.gd             #   Godot editor → .pck exporter
+│       └── map_registry_server.py  #   Python HTTP registry server
+└── docs/mapmaking/
+    ├── 00-index.md                 # This document
+    ├── 01-getting-started.md       # Template project setup
+    ├── 02-building-geometry.md     # CSG & prefab guide
+    ├── 03-lighting-and-env.md      # Lighting & baking
+    ├── 04-validation.md            # Validator usage
+    ├── 05-packaging-and-shipping.md# Publishing pipeline
+    └── 06-faq-and-troubleshooting.md
+```