Repo ↗ · Source README ↗ · Markdown & license bundle

Image reference (original game): Sekiro: Shadows Die Twice · original-game artwork, provided by IGDB. Image rights remain with their respective owners. This illustrates the referenced original game, not the actual visuals of this rewrite or mod.

Source maintainer: AKJama · Revision: aa2c806a9f68 · Catalogued: 2026-10-12

Source license: MIT · LICENSE-APACHE · LICENSE-MIT · Article: Source README (format adapted)

The source README follows, with formatting adapted for this site and images replaced by source links. Feature, completion and testing claims belong to its authors and have not been independently playtested here. The Traditional Chinese translation was prepared with AI assistance.

sekiro-rs

A Rust and Bevy reimplementation of Sekiro: Shadows Die Twice that runs on your own installed copy of the game.

This is a fan project for study.
It is not affiliated with or endorsed by FromSoftware or Activision.
No game files are in this repository, only code.
To build anything you need your own copy of Sekiro (Steam, v1.6.0.0), from which the tools here generate the data on your machine.

How it works

Sekiro is data-driven, so instead of hand-writing its behaviour this project rebuilds the engine and feeds it the game’s own data:

Behaviour Where the game keeps it What sekiro-rs does
Player state machine (inputs, guard, deflect, attacks, jumps, dodges) Havok Script bytecode (c0000.hks) Runs it in a small Havok Script VM written in Rust
States and animation selection Havok behaviour graphs Behaviour graph runtime
Timings (hit frames, deflect windows, cancel windows) TAE events TAE runtime
Numbers (damage, posture, guard rates, recovery) PARAM tables Param reader driven by Paramdex definitions
Animation Havok spline-compressed HKX Decoded to sampled clips with root motion
Characters FLVER, TPF, MTD Exported to skinned, textured GLB
Levels MSB, map pieces, Havok collision, ledge and grapple edges All ten maps exported and walkable
Enemy AI Lua 5.0 battle scripts, EMEVD event scripts Own Lua VM and goal runtime; boss phases from the map’s events
Rendering GPARAM draw params, compiled shaders Fog, exposure, tone mapping, bloom and grading reimplemented from the game’s own shaders (docs/SHADERS.md)
Engine-side combat rules the executable Recovered by static analysis and rewritten as original Rust (docs/COMBAT-RULES.md)

Status

Work in progress.
What runs today:

  • Combat: deflect, block, posture both ways, perilous attacks and Mikiri, deathblows with the game’s own throw pairs and deathblow camera, death and respawn.
  • Bosses and enemies: the Great Shinobi Owl on the Ashina Castle roof (both phases, his tools), Genichiro Ashina on the castle keep roof (both deathblows, the Way of Tomoe hand-over, his lightning and Lightning Reversal), Ashina soldiers; every character placed in the game loads by id.
  • Boss brain: an AI that learns how you fight and adapts the boss (docs/BRAIN.md), for the Owl, Genichiro and the soldier.
  • Movement: run, sprint, jump with air control, step, crouch, ledge hang and climb, grappling hook (arcs, mid-air and chained), wall hug, swimming and diving, fall death.
  • World: all ten maps load and are walkable, with light probes, point lights, layered moss and snow materials, and the game’s fog, tone mapping, bloom and colour grading.
  • Not yet: the game’s particle effects (simple stand-ins are used), sky domes, menus beyond the start and pause menus, items, prosthetic tools and combat arts, stealth, and most enemies’ special mechanics.

The detailed state is in STATUS.md and docs/PROGRESS.md.

Build and run

Requires Windows, Rust (stable, MSVC, with the Visual Studio C++ build tools) and your own Steam copy of Sekiro v1.6.0.0.
Point the tools at your install with --game <folder> or the SEKIRO_DIR environment variable if it is not in the default Steam location.
Extraction only reads the game folder and writes everything to the gitignored cache/ folder (about 50 GB in total, so leave room).

# 1. Public community reference files (archive keys, file names, param definitions)
./tools/fetch-refs.ps1
# 2. Unpack your install into cache/raw (about 32 GB)
cargo run --release -p sekiro-extract -- unpack
# 3. Params first, then the maps (the character list comes from the maps)
cargo run --release -p sekiro-extract -- params
foreach ($m in 'm10_00_00_00','m11_00_00_00','m11_01_00_00','m11_02_00_00','m13_00_00_00','m15_00_00_00','m17_00_00_00','m20_00_00_00','m25_00_00_00','m89_00_00_99') { cargo run --release -p sekiro-extract -- map $m }
# 4. Characters and animations (defaults to Wolf and every placed character)
cargo run --release -p sekiro-extract -- models
cargo run --release -p sekiro-extract -- anims
# 5. Play
cargo run --release -p sekiro-game

Play the baseline game

No accounts, keys or models are needed: this is the game as FromSoftware wrote it, with every enemy running its own original AI.

Running the game with no arguments opens the start menu: pick the fight, the place, the AI (leave it on “Lua”, the game’s own AI), the time of day and god mode, then Start.
Esc in a fight opens the pause menu (resume, back to the start menu, quit).

The same choices work as command-line flags, which skip the menu:

$game = 'target/release/sekiro-rs.exe'
& $game --arena owl --progression castle-roof          # Great Shinobi Owl on the castle roof
& $game --arena genichiro --progression castle-roof    # Genichiro on the castle keep roof
& $game --arena genichiro --genichiro-phase tomoe       # straight to the Way of Tomoe lightning phase
& $game --play --enemy soldier                          # an Ashina soldier on a flat floor
& $game --play --map m11_00_00_00 --start 3 --no-enemy  # walk around a map

Useful flags: --progression castle-roof (Wolf’s attack power at that point in the game), --god (you cannot die), --immortal (you cannot die but posture still breaks), --hour 0-23 (time of day), --enemy cXXXX (any character by id).

Controls: WASD move, mouse camera, left mouse attack, right mouse guard and deflect, Space jump, Shift step (hold to sprint), C crouch, Q lock-on, E grab a ledge or hug a wall, F grappling hook, Esc pause menu.
A gamepad works too.

The boss brain

The boss brain replaces the boss’s choice of moves with a model-driven controller that learns how you fight and adapts, while the boss keeps his own moves, timings and rules.
It sees only what a player could see, and it remembers you across sessions (memory in the gitignored logs/memory/); in our testing it becomes very hard after about 20 fights.
It currently supports the Great Shinobi Owl, Genichiro and the Ashina soldier.

It has two parts:

  • The coach reviews your fights (after each fight and about every 30 seconds mid-fight) and writes a game plan. It runs through a command-line agent on your own subscription, so it needs no API key.
  • The checkpoint chooser (optional) is a small, fast model that switches between the coach’s prepared plans at key moments in a fight. It uses the OpenAI API and needs an API key.
  1. Install the Codex CLI and sign in with your ChatGPT plan (codex login).
    The game starts it isolated, without your other Codex settings, memories or project files.
  2. Optional, for the checkpoint chooser: copy .env.example to .env in the repository folder and set OPENAI_API_KEY.
    .env is gitignored; never commit it.
  3. Play:
& $game --arena owl --progression castle-roof --brain coach --coach codex --brain-overlay
& $game --arena genichiro --progression castle-roof --brain coach --coach codex --brain-overlay

Or pick “Coach brain” as the AI in the start menu.

What it costs and how fast it is

Measured on 11 October 2026:

Part Runs through Typical time per call Typical tokens per call Paid by
Coach, --coach codex (default model gpt-6.1-sol) Codex CLI about 5 to 25 s about 11k to 19k your ChatGPT plan’s usage
Coach, --coach claude Claude Code CLI (claude -p) about 60 to 120 s about 96k to 161k your Claude plan’s usage
Coach, --coach api OpenAI API depends on model similar to Codex API key, billed
Checkpoint chooser (gpt-6-luna) OpenAI Decisions API fast, about 100-byte requests about 300 API key, billed (about $0.002 for a 9-fight session)

The Codex coach is the recommended one: it was by far the fastest and leanest in our tests.
The Claude coach works but is slow, because the CLI loads your whole Claude Code setup on every call; if you prefer it, your own coding agent can help you tune it.
The overlay footer (--brain-overlay, F8) counts tokens for the current fight and session.

Other brain options

  • --player <name> keeps a separate profile per player (the boss’s general knowledge is shared; what it learned about you is yours).
  • --brain-memory off plays without reading or writing memory.
  • --brain-stage lua|early|alive|outsmarted replays saved stages of the Owl’s learning, for comparisons and recordings.
  • --brain-token-budget N stops model calls after N tokens and falls back to the boss’s own AI; --brain-budget USD does the same for billed API spend.

Details, including how the plans, checkpoints and memory work: docs/BRAIN.md.

Layout

  • crates/formats: readers for the game’s formats.
  • crates/extract: sekiro-extract, turns your install into cache/.
  • crates/hks: Havok Script VM.
  • crates/sim: Bevy-free simulation (behaviour graph, TAE, input, body, combat).
  • crates/game: the sekiro-rs Bevy app.
  • docs/: formats, params, the player script interface and the combat rules, in our own words.

Tested setup

Windows 11 64-bit, Steam Sekiro app 814380, build 5794815 (game version 1.6.0.0), Rust 1.99 (MSVC), Bevy 0.19.1.
Other game versions are untested.

Research boundary

Format and engine research happens in local, gitignored folders (cache/ and re/) and is never committed.
That includes extracted game data, analysis databases and any decompiler output.
The Rust code in this repository is original and written from that research and from public community documentation; no game code is loaded, linked or copied into it.
Engine-side rules are documented in our own words in docs/, with confidence labels.

This is an AI-assisted project, developed with Anthropic Claude Code and OpenAI Codex, and reviewed and playtested by the author.

Disclaimer

sekiro-rs is an unofficial, non-commercial fan project made for education and research into game engine design and interoperability.
It is not affiliated with, endorsed by, or sponsored by FromSoftware, Inc. or Activision Publishing, Inc.

Sekiro: Shadows Die Twice and all of its content, including characters, models, textures, animations, audio, data and trademarks, belong to FromSoftware, Inc. and its publishers.
None of that content is included in or distributed with this repository.
This repository contains only original source code and documentation written for this project.

  • You need your own legitimately purchased copy of the game; the tools read it locally and never modify the installation or save files.
  • Everything derived from the game stays in the gitignored cache/ and re/ folders on your machine. Do not commit, upload or share those folders or anything generated into them.
  • This project is single-player only. It has no online features and does not interact with online services or anti-cheat systems.
  • No warranty is given; use it at your own risk.

If you are a rights holder and have a concern about this project, please open an issue and it will be addressed promptly.

See CREDITS.md for the community research this builds on.

Licensed under either of MIT or Apache-2.0 at your option.

License and provenance

The README and its translation retain MIT terms. Changes comprise translation, links and formatting. Editable Markdown, the original README, LICENSE and NOTICE files are included in the linked bundle. This grants no rights to the original games, their assets or trademarks.

LICENSE-APACHE

Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

LICENSE-MIT

MIT License

Copyright (c) 2026 AKJama

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.