tactical-shooter/client/tools/validate_map/README.md

Map Validator Scripts

Validator scripts for Tactical Shooter map scenes. Run against any .tscn file to check structural integrity, performance budget, and lighting correctness before packaging.

Usage

# From the project root or anywhere with --path pointing at the Godot project
godot --path client --script tools/validate_map.gd -- res://maps/mymap.tscn

The -- separates Godot engine args from user args. The scene path must be a res://-prefixed Godot resource path.

Exit Codes

Code	Meaning	Description
0	PASS	All checks passed, no warnings
1	WARNINGS	Passed with non-blocking suggestions
2	ERRORS	Failed — must-fix items found

Use exit codes in CI/CD pipelines to gate map merges:

godot --path client --script tools/validate_map.gd -- res://maps/mymap.tscn
if [ $? -eq 2 ]; then
    echo "Map validation FAILED — fix errors before submitting"
    exit 1
fi

Validator Modules

1. Scene Structure (validate_scene.gd)

• Scene root is a Node3D
• Required node types present: WorldEnvironment, LightmapGI
• Required Godot groups assigned to one node each: ct_spawn, t_spawn, buy_zone, bomb_site, cubemap_origin
• Node naming follows PascalCase convention

2. Polygon Count (validate_polycount.gd)

• Total mesh triangle count across all MeshInstance3D nodes ≤ 50,000
• Per-mesh breakdown printed for debugging
• Warns on individual meshes exceeding 5K triangles
• Warns if no MeshInstance3D nodes found (empty map)

3. Texture Sizes (validate_textures.gd)

• All material textures (albedo, normal, roughness, metallic, ORM, emission, AO) ≤ 1024×1024
• Checks StandardMaterial3D, ORMMaterial3D, and ShaderMaterial (Texture2D params)
• Warns on textures > 512×512 (suggested for secondary surfaces)
• LightmapGI baked textures checked separately

4. Lights & Lightmap (validate_lights.gd)

• Dynamic (non-baked) OmniLight3D + SpotLight3D ≤ 4
• DirectionalLight3D counts toward dynamic budget if light_bake_mode ≠ Static
• LightmapGI node present and baked (light_data ≠ null)
• Lightmap quality, bounces, texel scale, and max texture size checked
• WorldEnvironment configured with Environment resource
• ReflectionProbe presence and settings
• Warns on dynamic lights with shadows enabled (performance cost)

Architecture

client/tools/
├── validate_map.gd              # Main entry point: parses args, loads scene, runs modules
└── validate_map/
    ├── validate_scene.gd         # Scene structure validator
    ├── validate_polycount.gd     # Polygon count validator
    ├── validate_textures.gd      # Texture size validator
    └── validate_lights.gd        # Light/lightmap validator

All modules are @tool RefCounted scripts exporting a single validate(scene_root: Node, scene_path: String) -> Dictionary function.

Adding a New Validator

1. Create tools/validate_map/validate_<name>.gd extending RefCounted
2. Implement func validate(scene_root: Node, scene_path: String) -> Dictionary
3. Return {"pass": bool, "errors": [String], "warnings": [String]}
4. Add a _run_module("<name>", instance, scene_path) call in validate_map.gd:_ready()

Requirements

• Godot 4.x
• The map scene must be self-contained (all resources accessible via res:// paths)
• Run from a terminal (not embedded in a running game)