A source-linked knowledge base, coding companion, and reusable Codex skill for The Binding of Isaac modding.
Build with evidence, not plausible-sounding APIs. Isaac KDB brings searchable Lua/XML references, practical implementation patterns, graphics-production rules, and executable static checks into one local repository.
🎯 Primary target: Repentance+ and REPENTOGON, with explicit vanilla/version boundaries.
🧠 Agent-ready: this repository is the tboi-repentogon-modding skill.
🔎 Offline lookup: generated catalogs include source paths and pinned revisions.
🧪 Honest status: broad static coverage—not an Isaac emulator or runtime certification.
| Area | Included snapshot |
|---|---|
| Research | 30 registered sources with authority, revision and confidence information |
| API lookup | 11,456 indexed symbols across APIs, callbacks, enums and XML |
| Lua reference | 135 classes/namespaces and 2,634 function records |
| Callbacks | 438 ecosystem-specific records, including REPENTOGON modifications |
| Enums & XML | 179 enum records and 35 attributed XML schemas |
| Implementation | 67 patterns, 12 golden static reference fragments and two starter examples |
| Evaluation | 191 configured cases, 15 red-team cases, five acceptance-regression tests and 13 graphics-audit tests |
| REPENTOGON test reference | 144 official TestMod modules indexed by test scope |
Counts describe this snapshot, not unique engine functions or exhaustive semantic coverage. Vanilla/REPENTOGON overlaps are intentional. Configured evals check evidence and fixtures; they do not grade every possible generated mod. See KB health.
- Items and combat: passive/active items, stat caches, tears, damage events, pickups and cache-managed familiars.
- Entities and encounters: filtered NPC callbacks, entity-owned state machines, animation-driven attacks and living-player co-op targeting.
- Engineering: state ownership, lifecycle, deterministic RNG, save schemas, migrations, performance, compatibility and optional-library boundaries.
- REPENTOGON: additions versus modified vanilla behavior, debug ImGui, console commands, source conflicts and dependency checks.
- Resources: XML, rooms, ANM2, PNGs, costumes, audio and graphics contracts, with explicit distinctions between scaffolds and finished content.
The workflow starts by inspecting the existing mod, favors small compatible patches, and never treats a believable API name as evidence.
The graphics workflow connects:
Lua/XML → ANM2 → spritesheet rectangles → animation events → in-game rendering
It covers original Isaac-compatible pixel art, native-scale readability, consistent frames and pivots, directional sprites, costumes, attack telegraphs, spritesheet-first layout and temporary-placeholder handling.
Use the animation contract to keep art and code aligned, then apply the visual QA prompt. The auditor checks PNG decoding, dimensions, alpha requirements, crop bounds, sheet/layer IDs, timing, animation/event contracts and asset-readiness metadata.
A PNG or a valid ANM2 alone is not finished graphics. Without an observed
in-game visual test, the workflow records visual_runtime_tested: false.
Requires Python. Pillow enables PNG decoding/alpha/crop checks. If luac is
available, validation also invokes it for actual Lua syntax compilation.
git clone https://github.com/Angelicismo01/isaackdb.git
cd isaackdb
python -m pip install Pillow
python scripts/validate_kb.pyAudit an existing mod from the KB directory:
python scripts/validate_kb.py --project "C:\path\to\mod" --ecosystem repentogonUse --ecosystem vanilla for vanilla-targeted code. Run graphics checks directly:
python scripts/gfx_audit.py "C:\path\to\mod"
python scripts/gfx_audit.py "C:\path\to\mod" --releaseThe release check requires the documented KB-owned assets/gfx-manifest.json,
final-asset status and runtime attestations. This is not an Isaac engine format,
and the scanner cannot verify whether an author's runtime attestation is true.
Ask Codex's skill installer to install this repository as a personal skill:
Use $skill-installer to install https://github.com/Angelicismo01/isaackdb
as the personal skill tboi-repentogon-modding.
Then request it explicitly:
Use $tboi-repentogon-modding to review my Repentance+ mod.
Verify callbacks, familiar ownership, XML paths and animation contracts.
The description supports automatic selection for relevant tasks. SKILL.md is the compact entrypoint; detailed material is read when needed. This is a skill with local scripts, not an MCP server. A copied installation is a snapshot; synchronize it after updating the checkout.
| Need | Start here |
|---|---|
| Exact API or enum | Symbol index |
| Callback arguments and returns | Callback catalog |
| Natural-language task | Task routes |
| Implementation patterns | Pattern index |
| Coding and review discipline | Standards and review prompts |
| Debugging | Decision tree |
| Graphics production | GFX guide |
| Evidence and conflicts | Sources |
| Tests and limits | Acceptance review and limitations |
The suite checks repository structure, provenance, exact symbols, regression fixtures, selected callback argument mistakes, XML structure, resource references and PNG/ANM2 contracts. It protects against invented global-table members and lost camel-case enum values.
validate_kb.py is read-only apart from Python bytecode caching;
health_check.py is its compatibility alias. It does not rebuild catalogs or
rewrite reports. Dynamic Lua/dataflow, gameplay balance, runtime performance,
co-op edge cases and visual quality require separate inspection and game tests.
Production acceptance remains partial: no Isaac runtime was run for this snapshot. Boss/character/stage examples are not complete shipped encounters. Some acceptance fixtures lack final art; golden examples are reference fragments, not twelve install-and-play mods.
python scripts/update_kb.py
python scripts/update_kb.py --apply --check-linksThe updater snapshots catalogs, reports source revisions, and stops before
regeneration when a checkout differs from the curated pin. --apply permits
fetching/cloning upstreams. Review diffs, compatibility and licensing before
accepting a new pin. Raw checkouts live in ignored .cache/upstreams/.
The recorded safety test detected IsaacScript pin drift and deliberately stopped. IsaacAgent was unavailable and was not ingested. These gaps remain visible rather than being presented as successful imports.
Primary references include REPENTOGON, Wofsauge IsaacDocs, Isaac Blueprints, and the official REPENTOGON TestMod. The registry records pins, authority and license notes; source priority explains conflict handling.
Upstream material retains its own licensing. Vendored XML schemas include their attribution/license; do not assume all referenced projects share it. No proprietary game assets or full upstream source caches are bundled. This is an independent community project, not an official Isaac or REPENTOGON product.