# 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
```