security-game/tools/README.md

Gig Line Tools

Developer and release tooling for Gig Line. Nothing in this directory runs in the game at runtime; the tools generate or audit committed assets, capture visual evidence, and build/publish releases. They are intentionally kept outside src/ and outside the exported runtime scripts.

File inventory

All tracked source files are listed here; generated __pycache__/ and .ruff_cache/ contents are ignored.

File	Kind
README.md	this guide
asset_pipeline.py	Python: image generation and audit
bake_ao.py	Python/Blender: AO baking
blender_assets.py	Python/Blender: character, gear and prop library
build_releases.sh	shell: release export/packaging
check_docs.py	Python: documentation gate
check_screenshots.sh	shell: gallery capture/compare
export_venues.gd	GDScript: venue .tres export
export_venues.gd.uid	Godot UID sidecar
generate_textures.py	Python: procedural/AI textures
make_normal_maps.py	Python: derived normal maps
model_pipeline.py	Python/Blender: prop models and atlases
npc_baseline.py	Python: NPC baseline/compare sheets
npc_pipeline.py	Python/Blender: NPC base and texture maps
npc_proportions.py	Python: exported-GLB proportion audit
openrouter_judge.py	Python: shared OpenRouter judge client
publish_release.sh	shell: release upload/preflight
refboard.py	Python: licensed reference candidate board
refcollect.py	Python: local-only image research fetcher
scene_concepts.py	Python: concepts, texture processing, realism
screen_designs.py	Python: screen mockups, compare and judge
three_up.py	Python: photo/concept/capture boards
tests/	Python tooling tests, test README and package marker
tests/README.md	test-run instructions
tests/__init__.py	package marker for module-style discovery

Tests in tests/

Test	Covers
test_asset_pipeline.py	image roles, generation helpers and audit
test_blender_assets.py	catalogue, contract, fit, texels and manifest
test_check_docs.py	README/link/image documentation gate
test_generate_textures.py	texture generation helpers
test_model_pipeline.py	prop models, palette atlas and GLB output
test_model_review.py	scorecard coverage for the 3D review
test_npc_baseline.py	baseline sheet/comparison selection
test_npc_pipeline.py	NPC contract, textures and committed model
test_npc_proportions.py	exported proportion measurements
test_openrouter_judge.py	model selection, retries and errors
test_refboard.py	licence gate, recent filter and row output
test_refcollect.py	search parsing, retries and local downloads
test_scene_concepts.py	processing, promotion, references and judge
test_screen_designs.py	design catalogue, compare and judge
test_three_up.py	three-up composition and captions

Run the suite from the repository root:

python3 -m pip install -r requirements-tools.txt
python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py'

Categories

1. Asset generation and authoring

These produce or modify committed assets. Prefer a clean worktree, inspect the diff, and run the matching audit before committing generated files.

Tool	Purpose	Typical command
blender_assets.py	Catalogue/build/audit/inspect/fit/texel/sheet the character, gear and prop library. build/render need Blender; audit/fit/inspect are standalone.	python3 tools/blender_assets.py audit
npc_pipeline.py	Prepare AI fabric tiles, derive outfit palettes, build npc_base, audit the NPC contract.	python3 tools/npc_pipeline.py audit
bake_ao.py	Blender AO bake for library assets.	flatpak run org.blender.Blender --background --python "$PWD/tools/bake_ao.py" -- --only npc_guard
npc_proportions.py	Measure exported GLBs against the stylized proportion guide.	python3 tools/npc_proportions.py report
npc_baseline.py	Compose neutral baseline sheets and before/after comparisons.	python3 tools/npc_baseline.py sheet --dir tmp/npc-baseline
asset_pipeline.py	Generate, crop, resize, seam-fix and audit images by role.	python3 tools/asset_pipeline.py audit assets/textures
generate_textures.py	Procedural texture generation with an optional AI mode.	python3 tools/generate_textures.py
make_normal_maps.py	Derive tangent normal maps from albedo textures.	python3 tools/make_normal_maps.py <texture.png>
model_pipeline.py	Build low-poly props and single-material palette atlases.	python3 tools/model_pipeline.py build
scene_concepts.py	Generate concept frames, process/promote texture picks, and run the realism judge.	python3 tools/scene_concepts.py audit
screen_designs.py	Generate screen-design references and compare/judge captures.	python3 tools/screen_designs.py compare
three_up.py	Compose labelled real-photo/concept/capture boards.	python3 tools/three_up.py compose --help
openrouter_judge.py	Shared OpenRouter client for model selection, retries and JSON parsing.	normally imported by the judge tools

2. Reference research and provenance

Tool	Purpose	Notes
refboard.py	Search Wikimedia Commons (search/geo/category), gate by licence and age, fetch candidates, emit sidecar rows.	Committed-board source; run with the licence gate.
refcollect.py	DuckDuckGo image search/fetch and local contact sheets.	Local-only research: downloads stay in tmp/research/, never committed.
three_up.py	Pair a real reference, generated concept and current capture in one review board.	The photos remain evidence, not shipped art.

3. Validation and review

Tool	Purpose	Typical command
check_docs.py	Verify README coverage, local links and tracked-image links.	python3 tools/check_docs.py
check_screenshots.sh	Re-render the committed gallery and run the Pillow comparison.	./tools/check_screenshots.sh
npc_baseline.py	Baseline/compare character contact sheets.	see above
npc_proportions.py	Proportion gate on exported GLBs.	see above
screen_designs.py compare/judge	Screen-design drift gate and optional vision review.	python3 tools/screen_designs.py compare
scene_concepts.py realism	Optional realism-review and judge pass.	python3 tools/scene_concepts.py realism --run <dir>

4. Runtime/content export

Tool	Purpose	Typical command
export_venues.gd	Export content/venues/*.tres from ScenarioFactory.	godot --headless --path . --script res://tools/export_venues.gd

5. Build and release

Tool	Purpose	Typical command
build_releases.sh	Export Linux/Windows/macOS/Web and package the optional Desktop HQ zip. Run from a clean worktree.	./tools/build_releases.sh
publish_release.sh	Preflight artifacts/free space, write SHA-256 checksums, upload with rollback, optional retention pruning.	PUBLISH_DRY_RUN=1 ./tools/publish_release.sh

The clean-worktree requirement is important: a normal working tree may contain ignored tmp/ and build/ content that Godot can pack into the export.

6. Tests

All Python tooling tests live in tests/. They use the repository's requirements-tools.txt (Pillow) and do not start Godot or Blender. See tests/README.md for the exact discovery command.

Project AI skills

Two project-authored skills now live under ../.agents/skills/ and are tracked in the repository:

• gig-line-blender-asset-contract — contract, command order, failure playbook and verification for Blender/NPC/gear/prop work.
• gig-line-release-qa — test/smoke matrix, visual gates, clean build, checksums, tag/publish and release records.

The third-party blender-skills pack remains local/gitignored. These project skills are guidance only; they do not move scripts into .agents, add runtime dependencies or replace the tools above.

Remaining skill candidate

• gig-line-reference-provenance (medium value). Guide refboard.py vs refcollect.py: committed Wikimedia-sourced boards with sidecars versus local-only tmp/research/ downloads, and the rule that generated concepts never override photo evidence. This is more of a policy skill than a command skill.

Keep as scripts

• asset_pipeline.py, generate_textures.py, make_normal_maps.py, model_pipeline.py and scene_concepts.py are general generation/processing utilities. A skill should point to their documented commands rather than duplicate them; several call paid APIs and must stay human-triggered.
• screen_designs.py and scene_concepts.py judge modes are optional, network/budget-dependent review aids, not deterministic CI gates.
• openrouter_judge.py is an implementation detail imported by other tools.
• check_docs.py and export_venues.gd are short, single-purpose commands; documenting them in this README and docs/asset-tooling.md is enough.
• npc_baseline.py, npc_proportions.py and three_up.py are better included as references/steps inside the proposed asset or release skill than exposed as separate skills; fragmenting them would increase routing mistakes.

Do not move scripts into .agents/skills/: the local Blender skill pack is gitignored guidance, while these tools are tracked project code with tests and CI-relevant contracts. A future skill should reference this directory and the project docs, not fork the implementation.