{"id":51468719,"url":"https://github.com/bssth/sacred-sdk","last_synced_at":"2026-07-06T14:30:50.438Z","repository":{"id":365023375,"uuid":"1238287907","full_name":"bssth/sacred-sdk","owner":"bssth","description":"Lua scripting framework and bytecode toolchain for Sacred Gold (2004) — write mods without patching the EXE","archived":false,"fork":false,"pushed_at":"2026-06-15T13:37:45.000Z","size":2091,"stargazers_count":5,"open_issues_count":25,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-15T15:23:05.859Z","etag":null,"topics":["bytecode","dll-injection","game-modding","modding-tools","reverse-engineering","sacred-gold"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bssth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"bssth"}},"created_at":"2026-05-14T01:47:06.000Z","updated_at":"2026-06-15T13:38:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bssth/sacred-sdk","commit_stats":null,"previous_names":["bssth/sacred-sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bssth/sacred-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bssth%2Fsacred-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bssth%2Fsacred-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bssth%2Fsacred-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bssth%2Fsacred-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bssth","download_url":"https://codeload.github.com/bssth/sacred-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bssth%2Fsacred-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35195590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytecode","dll-injection","game-modding","modding-tools","reverse-engineering","sacred-gold"],"created_at":"2026-07-06T14:30:49.310Z","updated_at":"2026-07-06T14:30:50.409Z","avatar_url":"https://github.com/bssth.png","language":"C++","funding_links":["https://github.com/sponsors/bssth","https://ko-fi.com/V7V51ZQ1RH"],"categories":[],"sub_categories":[],"readme":"# SacredSDK\n\nA modern modding toolkit for **Sacred Gold** (Ascaron, 2004) — write\nmods in **Lua** without ever modifying the original game files.\n\n[![Verified](https://img.shields.io/badge/verified-Steam%20build%202.0.2.28%20%282006--10--13%29-brightgreen)]()\n[![License](https://img.shields.io/badge/license-MIT-blue)]()\n[![Status](https://img.shields.io/badge/status-alpha-orange)]()\n![MIU](https://img.shields.io/badge/made_in-Ukraine-ffd700?labelColor=0057b7)\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/V7V51ZQ1RH)\n\n---\n\n## What is it\n\nSacredSDK is a DLL that Sacred loads at startup (via the `ijl15.dll`\nproxy slot — no patching of `Sacred.exe`). On load it:\n\n1. **Bakes Lua mods** at `custom/lua/**/*.lua` into Sacred's native\n   bytecode (the `FunkCode.bin` format used by every quest, dialog,\n   and creature in the game).\n2. **Patches resource lookups** so any file Sacred opens can be\n   transparently swapped for `custom/\u003csame-path\u003e`.\n3. **Hooks the resource resolver** so Lua mods can react to game-time\n   events (NPC dialog, kill banners, quest progress) and mutate hero\n   state (gold, inventory).\n\nThe Steam install stays bit-for-bit untouched — mods live entirely\nunder `\u003cgame\u003e/custom/`. Uninstall = delete that directory.\n\n---\n\n## What you can do today\n\n| Capability | Status | Notes |\n|---|---|---|\n| **Reskin any vanilla quest's text** | ✅ stable | `T.named(\"HQ_3_2_1_Log_Title\", \"My new title\")` |\n| **Inline-string mods** | ✅ stable | `T\"Some text\"` auto-registers in `global.res` |\n| **Per-class boot scripts** | ✅ stable | qbits, variables at hero spawn |\n| **Dialog scenes from Lua** | ✅ stable | `d.trigger / d.line / d.emit` builders |\n| **Native `has_item` predicate** | ✅ stable | bytecode-level inventory check |\n| **Native `give_gold` opcode** | ✅ stable | bake-time gold ops |\n| **Runtime callbacks** (`sacred.on_trigger`) | ✅ working | fires on resource queries |\n| **`ctx:give_gold(N)`** in handlers | ✅ working | event-bus, plays coin sound + floating text |\n| **`ctx:has_item(N)`** (equipment) | ✅ working | scans 18 wear slots |\n| **`ctx:notify(text)`** | ✅ working | top-of-screen toast banner |\n| **In-game overlay** | ✅ working | F11 capture / F12 hide / F10 snapshot |\n| `ctx:has_item` (backpack) | 🟡 TODO | needs bag-array RE |\n| `ctx:set_qbit` runtime | 🟡 stub | bake-time works |\n| Native engine banner | 🟡 TODO | currently ImGui overlay toast |\n| Brand-new quest at spawn | ❌ blocked | needs quest-book RE |\n\nSee [docs/community-refs.md](docs/community-refs.md) for the full\nwishlist with effort estimates.\n\n---\n\n## Quick start\n\n```lua\n-- save as: \u003cgame\u003e/custom/lua/bin/TYPE_NPC_SERAPHIM/FunkCode.lua\nlocal T = require \"text\"\nlocal v = require \"vanilla\"\n\n-- Re-skin the Seraphim main quest into a custom narrative.\nT.named(\"HQ_3_2_1_Log_Title\",  \"The Lost Tome of Ancaria\")\nT.named(\"HQ_3_2_1_Log_Header\", \"Chapter 1 — A Curious Heist\")\nT.named(\"HQ_3_2_1_Log_Qstart\",\n  \"A young monk runs up to you in Bellevue, breathless. \" ..\n  \"An ancient tome was stolen from the monastery library...\")\n\nreturn v.load \"bin/TYPE_NPC_SERAPHIM/FunkCode\"\n```\n\nLaunch Sacred → start a new Seraphim → accept Leandra's quest → open\nthe journal. You'll see your new title and text where vanilla had\n\"River Pirates\".\n\nThe full reference is in **[docs/MODDING_GUIDE.md](docs/MODDING_GUIDE.md)** —\nread that first.\n\n---\n\n## Anatomy\n\n```\n\u003cSacred Gold install\u003e/\n├── ijl15.dll               ← SacredSDK proxy (replaces stock)\n├── ijl15_real.dll          ← original, renamed\n├── bin/, scripts/, …       ← vanilla, never touched\n└── custom/\n    ├── lua/\n    │   ├── lib/            ← stdlib (quest / dialog / text / events / …)\n    │   ├── examples/       ← copy-paste starters (01..07)\n    │   └── bin/            ← YOUR mods live here, mirror of bin/\n    │       └── TYPE_NPC_*/\n    │           ├── QuestCode.lua\n    │           └── FunkCode.lua\n    └── bin/                ← auto-generated .bin files (served to Sacred)\n```\n\nThere are three authoring layers (high → low):\n\n1. **High level** — `lib/quest.lua`, `lib/dialog.lua`, `lib/text.lua`.\n   One Lua line per quest primitive.\n2. **Mid level** — `lib/funkcode.lua`, `lib/raw.lua`. Direct bytecode\n   builders by opcode name.\n3. **Low level** — `lib/unsafe.lua`, `raw.hex\"…\"`. Raw byte literals.\n\nRound-trip is byte-perfect for 132/132 vanilla `.bin` files.\n\n---\n\n## Examples (in `custom/lua/examples/`)\n\n| File | Demonstrates |\n|---|---|\n| `01_hello.lua` | minimal mod that declares state |\n| `02_text_swap.lua` | bulk-rewrite vanilla via `gsub` |\n| `03_dialog_block.lua` | author a dialog scene from scratch |\n| `04_full_quest.lua` | small standalone quest |\n| `05_conditional_dialog.lua` | native Sacred branching skeleton |\n| `06_sidequest.lua` | **start here** — full side-quest template |\n| `07_runtime_triggers.lua` | `sacred.on_trigger` patterns |\n\n---\n\n## Project status\n\n**Alpha.** Core pipeline (Lua → bake → byte-identical bytecode) is\nproven and stable. Runtime hooks are working but require knowing\nwhich resource ids Sacred queries during your event of interest\n(discovery is iterative; see `docs/MODDING_GUIDE.md` § \"Runtime\ntrigger hooks\").\n\nPublic surface is **`docs/MODDING_GUIDE.md`** and the `custom/lua/lib/`\nmodules. The C++ side (DLL implementation, hooks, RE scripts) is in\nthe same SCM repository but separately gated — see § \"Repository\ncontents\" below.\n\n---\n\n## Repository contents\n\n```\nsdk/\n├── README.md               ← you are here\n├── docs/\n│   ├── MODDING_GUIDE.md    ← READ THIS FIRST\n│   ├── README.md           ← guide to the rest of the doc set\n│   ├── 01..22-*.md         ← RE journey (historical, technical)\n│   ├── community-refs.md   ← mined intel from community RE tools\n│   └── roadmap.md          ← where we are, where we're going\n└── tools/\n    ├── README.md           ← walkthrough: \"I want to X → run Y\"\n    ├── *.py                ← FunkCode pipeline, globalres edits, quest\n    │                          dumpers, sacred_hash, balance_diff, …\n    ├── hash_names.csv      ← 23 123-entry hash dictionary\n    ├── smoke_test_proxy.bat\n    └── ghidra/             ← Java scripts for headless Ghidra RE\n        └── README.md\n```\n\nThe **DLL sources** (C++) and the **Lua stdlib bundled into the DLL**\nship in a separate distribution channel (binary release) and will be\nopened in a later push when the public API surface stabilises.\n\nIf you just want to run mods today, the binary release ships with all\nthe runtime bits pre-built — clone this repo only if you want to\nread, contribute to, or extend the documentation and the Python\ntooling.\n\n---\n\n## Verified on\n\nSteam Sacred Gold, build **2.0.2.28** (2006-10-13). The DLL doesn't\ndo version detection; other builds may work but have not been\ntested. If you try one, please open an issue.\n\n---\n\n## Non-goals\n\n- Multiplayer mod scripting (Sacred LAN protocol RE is on the\n  wishlist but not started).\n- Asset replacement (textures, models, sounds) — these are in\n  `.pak`/Granny formats; see `docs/community-refs.md` for the\n  community tools that handle them.\n- \"ReBorn HD\"-style EXE patching — SacredSDK is a runtime DLL only,\n  not a patch.\n\n---\n\n## Acknowledgements\n\n- **Thorium** (2007 unofficial patch 2.29) — recovered global.res\n  loader detour and focus-busy-wait fix that we ported to runtime.\n- **SonicMouse** (SacredGameTools) — save-file format,\n  `TINCAT2.DLL` networking layout.\n- **The Resacred remake project** — pak/keyx format reverse\n  engineering, item/tile structs.\n- The broader Sacred modding community for two decades of\n  reverse-engineering notes.\n\n---\n\n## License\n\nMIT. See `LICENSE` (or fall back to standard MIT terms — this is\nstrictly fan modding work; no Ascaron/Encore IP is redistributed).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbssth%2Fsacred-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbssth%2Fsacred-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbssth%2Fsacred-sdk/lists"}