# ============================================================================
# nss5-forge -- .gitignore
#
# Written BEFORE `git init`, deliberately. Git history is permanent: a file
# committed once stays in every clone forever, and removing it later means
# rewriting history and invalidating every existing clone. There is exactly one
# moment when this is free to get right, and it is before the first commit.
# ============================================================================

# ----------------------------------------------------------------------------
# 1. THE ORIGINAL GAME -- NEVER COMMIT ANY OF THIS
#
# New Star Soccer 5 is a commercial product, still sold on Steam (appid 212780).
# Its executable and its media are the property of New Star Games Ltd. This
# repository contains our reconstruction of the SOURCE, and a description of
# where the original data lives -- never the data itself.
#
# Every project in this space enforces the same rule the same way, in the
# .gitignore rather than in prose: zeldaret/oot ignores *.z64, n64decomp/sm64
# ignores *.z64/*.mio0, diasurgical/devilutionX ignores *.mpq with the comment
# "Don't accidently commit the diabdat.mpq", OpenXcom ignores bin/UFO.
#
# Run `python scripts/setup.py` to populate these from your own copy.
# ----------------------------------------------------------------------------
/binary/*
!/binary/.gitignore
!/binary/README.md
!/binary/checksums.json

*.exe
*.dll

# Original media, copied out of your install by scripts/setup.py
GameMedia/
EngineMedia/
Inc/
Settings/
New Star Soccer 5/

# ----------------------------------------------------------------------------
# 2. TOOLCHAIN -- fetched, never vendored
#
# BlitzMax, Ghidra and the JDK are all publicly downloadable, so the repo holds
# the recipe and the pinned version, not the 8.5 GB of ingredients. Vendoring is
# reserved for tools that cannot be obtained any other way -- n64decomp/sm64
# commits actual SGI IDO compiler binaries because a 1990s SGI compiler is
# unobtainable. Nothing we depend on is in that category.
# ----------------------------------------------------------------------------
/tools/

# ----------------------------------------------------------------------------
# 3. BUILD OUTPUT
#
# src/assembled/ is generated in full by scripts/assemble.py. It is output, not
# source: 222 MB of it, including three .exe files and a 65 MB .bmx/ folder of
# compiler intermediates.
# ----------------------------------------------------------------------------
/src/assembled/
.bmx/
*.o
*.a
*.obj
*.pdb
*.ilk

# ----------------------------------------------------------------------------
# 4. DERIVED FROM THE ORIGINAL BINARY
#
# Ghidra output and everything downstream of it. Regenerated by setup.py from
# your own copy of the game. zeldaret/oot ignores `extracted/` for exactly this
# reason, and zeldaret/mm additionally ignores the disassembly itself.
# ----------------------------------------------------------------------------
# NOT everything here is derived. Twelve files in extracted/ are the build's INPUTS,
# not its outputs, and every one of them is required for `python scripts/assemble.py`
# to produce the game. They are the same kind of work product as the headers in
# src/recovered/*.bmx, which are tracked. Ignoring them shipped the tooling and
# withheld the working game -- verified from a tracked-files-only checkout:
# assemble.py died on the first missing one, and with the five adjudication files
# alone it merged 0 Global aliases instead of 1,280, which is the build whose player
# cannot move, whose animation runs 4.8x too fast and which crashes on quit.
#
# The two groups differ in how they were made, not in how necessary they are:
#
#   ADJUDICATED -- hand-written, each row decided by reading the original's machine
#   code. Nothing regenerates these.
/extracted/*
!/extracted/global_alias_overrides.tsv
!/extracted/global_alias_adjudicated.tsv
!/extracted/global_address_adjudicated.tsv
!/extracted/globals_type_overrides.tsv
!/extracted/globals_corrections.tsv
#   The one-name-two-slots backlog scripts/find_name_collisions.py --check ratchets
#   against. Not a build input, so it is absent from setup.py's BUILD_INPUTS and
#   assemble.py's _REQUIRED_INPUTS; it is tracked because a gate whose baseline is not
#   in the repository passes vacuously for everyone but the author.
!/extracted/name_collisions_baseline.tsv

#   RESOLVED -- produced once by the analysis tools from inputs that are NOT in the
#   repository (the Ghidra decompilation under extracted/decomp, ~72 MB, and
#   extracted/globals_final.tsv). Re-running their generators in a clean clone does
#   not reproduce them: build_alias_map.py picks a different canonical name without
#   globals_final.tsv, unify_names.py marks all 436 addresses UNGROUNDED without the
#   decompilation, and emit_unified_aliases.py then emits 6 rows instead of 704.
#   type_declaration_order.tsv and module_emission_order.tsv have no generator at all.
#   ~300 KB total, and with them a clone assembles a byte-identical source to a full
#   working tree's.
!/extracted/global_address_map.tsv
!/extracted/global_alias_map.tsv
!/extracted/global_alias_unified.tsv
!/extracted/global_alias_writers.tsv
!/extracted/module_globals_decoded.tsv
!/extracted/module_emission_order.tsv
!/extracted/type_declaration_order.tsv

# Run logs. Never useful to anyone else, and they name local paths.
/log/

# Generated locally by the tools that produce them. Useful while working,
# not part of what the repository publishes.
/docs/specs/10-probeability-classification.md
/docs/specs/11-reconstruction-dependency-graph.md
/ghidra-project/

# ----------------------------------------------------------------------------
# 5. GENERATED REPORTS AND SCRATCH WORK
#
# status/ is regenerated by the analysis scripts. Nothing here is authored.
# ----------------------------------------------------------------------------
/status/
/logs/
/scratch/
/scratchpad/
/verify/

# ----------------------------------------------------------------------------
# 6. LANGUAGE / EDITOR / OS
# ----------------------------------------------------------------------------
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/

.idea/
.vscode/
*.swp
*~

.DS_Store
Thumbs.db
desktop.ini

# ----------------------------------------------------------------------------
# 7. LOOSE OUTPUT
#
# Redirect targets that accumulate at the root during analysis sessions.
# ----------------------------------------------------------------------------
/out*.txt
/temp_out*.txt
/scratch_*.txt
/err.txt
/dbgcrash.txt

# ----------------------------------------------------------------------------
# 8. LOCAL WORKING FILES
#
# Scratch space. Nothing here is part of the deliverable.
# ----------------------------------------------------------------------------
/scripts/workflow/
/docs/archive/
