Shadow Fight 2 native desktop reconstruction

This repository reconstructs Shadow Fight 2 as an offline-first native Linux and Windows desktop game. It runs in a Unity 2022.3.62f2 desktop player and does not embed Android, start a virtual machine, or emulate the original ARM64 runtime.

The project combines two related efforts:

• a C# Unity bridge that reconstructs the game systems needed by the playable desktop runtime; and
• a native C++ proof pipeline that lifts selected original IL2CPP ARM64 methods to x86-64 and checks their behavior against the original instructions.

This is an active reverse-engineering port, not a finished parity release. Map, Shop, Profile, Settings, progression, persistence, non-fight Dojo training, and the fight loop are integrated, with recovered data and UI assets driving the runtime. Exact UI, combat, content, online-service, and platform parity still have known gaps. The detailed status is maintained in docs/CORE_SYSTEM_PORT_MATRIX.md. UI work also follows the hierarchy-first rules in docs/UI_RECOVERY_CONTRACT.md; known visual fallbacks are listed explicitly in docs/UI_PLACEHOLDERS.md.

If you want to implement or fix something yourself, start with the human-oriented implementation guide. It explains how to find the right owner and original evidence, make a focused change, add a smoke test, and verify it without damaging your normal save or unrelated worktree changes.

Run the existing Linux build

From the repository root:

./run_native_sf2.sh

The launcher writes sf2-native.log in the repository root. It currently selects the project's tested AMD GPU explicitly and forces OpenGL Core; adjust DRI_PRIME in the launcher if your GPU topology differs.

The Windows host can be started with run_native_sf2.bat from a packaged Windows build.

Controls

Input	Action
WASD or arrow keys	Move and choose attack direction
J / K	Punch / kick
L / I	Ranged weapon / magic
Space	Jump
R	Reset the active fight
1 / 2 / 3 / 4	Dojo training / Map / Shop / Profile
Esc	Back, pause, or close the active overlay
F1	Animation debug overlay
F2	Runtime UI editor
F3	System diagnostics
F4	Start or stop fight-trace recording

See docs/UI_EDITOR.md and docs/TRACE_CAPTURE_AND_DIFF.md for the editor and trace workflows.

Build the playable runtime

Prerequisites:

• Unity Editor 2022.3.62f2 with the target platform's Mono build support;
• Bash and standard Unix command-line tools;
• Python with UnityPy, ImageMagick, and the recovered SF2 source assets used by the build scripts; and
• the Switch reference data used to regenerate recovered UI and tactical assets.

The scripts default to the original development-machine paths. Override them when necessary:

export UNITY_EDITOR_ROOT=/path/to/2022.3.62f2/Editor
export SF2_MODDING_ASSETS=/path/to/SF2_ModdingAssets/Assets/assets
export SF2_SWITCH_DATA=/path/to/switch/romfs/Data

Build one complete platform package:

bash tools/build_platform.sh linux
bash tools/build_platform.sh windows

Or build both:

bash tools/build_all_platforms.sh

Outputs are written under dist/. For Windows-specific prerequisites, packaging details, and troubleshooting, see docs/BUILD_WINDOWS.md.

For a fast managed-code compile without resynchronizing the external asset corpus:

SF2_SKIP_ASSET_SYNC=1 bash tools/build_native_bridge.sh

The normal bridge build now installs the replacement corpus from ~/Downloads/xml.zip before regenerating assets. Override the archive with SF2_XML_ARCHIVE=/path/to/xml.zip. The installer replaces the prior data tree, preserves archive-relative identifiers, supplements only missing recovered model XML, and adds only quest-extension files referenced by the new graph. The empty <Quests /> files in quest_extensions are intentional shadow assets: they override defective same-named files in Unity bundles and must not be removed until bundle precedence is no longer needed.

The replacement stage lists reference 77 locations; 50 currently lack a complete recovered 1536 atlas family. To sync and compose the 27 available locations while reporting every missing family:

SF2_SKIP_MISSING_LOCATIONS=1 bash tools/build_native_bridge.sh

Validate changes

Subsystem smoke tests live behind the tools/validate_*.sh scripts. Run the relevant validators for focused work, or the complete suite with:

for test in tools/validate_*.sh; do
    bash "$test"
done

The native leaf-lifting probe is a separate CMake project. It expects the matching ../analysis_bundle and llvm-objdump:

cmake -S . -B build -G Ninja
cmake --build build
ctest --test-dir build --output-on-failure

The differential test is skipped when its Python environment lacks Unicorn and Capstone.

Repository layout

Path	Purpose
src/	Reconstructed C# bridge, grouped by game subsystem
direct_host/	Native Linux Unity player and staged runtime data
unity_probe/	Unity project used to build platform players
tools/	Build, asset recovery, trace, and validation tooling
docs/	Port matrices, evidence traces, milestones, and operator guides
CMakeLists.txt, src/probe.cpp	Native ARM64 leaf-lifting proof

The managed bridge is intentionally organized around shared owners rather than scene-local mock data: Data and User provide the content and persistence spines; Progression, Quests, Forge, Perks, and Settings own game rules; Fight and Moves own combat; and UI, Rendering, and Audio adapt those systems to the desktop player.

Reverse-engineering authority

Behavioral decisions should be justified by the recovered sources in this order:

1. Android Mono method bodies for control flow, formulas, and event ordering;
2. Switch IL2CPP metadata for clean names, signatures, and type layouts;
3. cross-build maps for connecting obfuscated Android code to clean identities;
4. packaged XML and recovered Unity assets for content and presentation; and
5. native traces and focused runtime tests for integration evidence.

The current evidence locations, dependency graph, and acceptance gates are in docs/CORE_SYSTEM_PORT_MATRIX.md. Recent automated and human-test progress is recorded in docs/MATRIX_COMPLETION_WORKLOG.md and docs/CORE_MATRIX_HUMAN_TESTS.md.