diff options
75 files changed, 2815 insertions, 11673 deletions
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index f884a10..6cef205 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -2,8 +2,14 @@ "image": "mcr.microsoft.com/devcontainers/rust:latest", "customizations": { "vscode": { - "extensions": ["rust-lang.rust-analyzer"] + "extensions": [ + "rust-lang.rust-analyzer" + ] } }, - "runArgs": ["--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined"] -} + "runArgs": [ + "--cap-add=SYS_PTRACE", + "--security-opt", + "seccomp=unconfined" + ] +}
\ No newline at end of file diff --git a/.gitea/workflows/docs-deploy.yml b/.gitea/workflows/docs-deploy.yml deleted file mode 100644 index ad9e0b9..0000000 --- a/.gitea/workflows/docs-deploy.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: Docs Deploy - -on: - push: - branches: - - master - -jobs: - deploy-docs: - name: Build and Deploy MkDocs - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v6 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: "3.14" - - - name: Install docs dependencies - run: pip install -r requirements.txt - - - name: Build MkDocs site - run: mkdocs build - - - name: Install rsync - run: | - sudo apt-get update - sudo apt-get install -y rsync openssh-client - - - name: Prepare SSH key - env: - SSH_KEY_B64: ${{ secrets.ROOT_CI_KEY_B64 }} - run: | - umask 077 - mkdir -p ~/.ssh - printf '%s' "$SSH_KEY_B64" | base64 -d > ~/.ssh/id_root_ci - chmod 600 ~/.ssh/id_root_ci - - - name: Deploy via rsync - env: - DEPLOY_HOST: ${{ secrets.FPARKAN_DEPLOY_HOST }} - DEPLOY_PORT: ${{ secrets.FPARKAN_DEPLOY_PORT }} - run: | - rsync -rlz --delete \ - -e "ssh -p ${DEPLOY_PORT} -i ~/.ssh/id_root_ci -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \ - site/ "gitea-runner@${DEPLOY_HOST}:./" diff --git a/.gitea/workflows/renovate.yml b/.gitea/workflows/renovate.yml deleted file mode 100644 index 9b407ca..0000000 --- a/.gitea/workflows/renovate.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: RenovateBot - -on: - schedule: - - cron: "@daily" - -jobs: - renovate: - container: ghcr.io/renovatebot/renovate:43 - runs-on: ubuntu-latest - - steps: - - name: Checkout code - uses: actions/checkout@v6 - - - name: Run renovate - run: | - renovate - env: - GITHUB_COM_TOKEN: ${{ secrets.RENOVATE_GITHUB_TOKEN }} - LOG_LEVEL: ${{ vars.RENOVATE_LOG_LEVEL }} - RENOVATE_CONFIG_FILE: renovate.config.cjs - RENOVATE_LOG_LEVEL: ${{ vars.RENOVATE_LOG_LEVEL }} - RENOVATE_REPOSITORIES: ${{ gitea.repository }} - RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }} diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml deleted file mode 100644 index cf314cb..0000000 --- a/.gitea/workflows/test.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Test - -on: [push, pull_request] - -jobs: - lint: - name: Lint - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: dtolnay/rust-toolchain@stable - with: - components: clippy - - name: Cargo check - run: cargo check --workspace --all-targets --all-features - - name: Clippy (deny warnings) - run: cargo clippy --workspace --all-targets --all-features -- -D warnings - - test: - name: Test - runs-on: ubuntu-latest - needs: lint - steps: - - uses: actions/checkout@v6 - - uses: dtolnay/rust-toolchain@stable - - name: Cargo test - run: cargo test --workspace --all-features -- --nocapture diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..cf918a7 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: + - package-ecosystem: "cargo" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "devcontainers" + directory: "/" + schedule: + interval: "weekly" diff --git a/.renovaterc b/.github/renovate.json index bc629bb..bc629bb 100644 --- a/.renovaterc +++ b/.github/renovate.json diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml new file mode 100644 index 0000000..0ec3a82 --- /dev/null +++ b/.github/workflows/mirror.yml @@ -0,0 +1,15 @@ +name: Mirror +on: [push] + +jobs: + mirror: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: yesolutions/mirror-action@master + with: + REMOTE: 'https://git.popov.link/fparkan.git' + GIT_USERNAME: ${{ secrets.GIT_USERNAME }} + GIT_PASSWORD: ${{ secrets.GIT_PASSWORD }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..01581b8 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,12 @@ +name: Test +on: [push, pull_request] + +jobs: + test: + name: cargo test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + - run: cargo check --all + - run: cargo test --all-features @@ -1,218 +1 @@ -*~ - -# temporary files which can be created if a process still has a handle open of a deleted file -.fuse_hidden* - -# KDE directory preferences -.directory - -# Linux trash folder which might appear on any partition or disk -.Trash-* - -# .nfs files are created when an open file is removed but is still being accessed -.nfs* - -# General -.DS_Store -.AppleDouble -.LSOverride - -# Icon must end with two \r -Icon - -# Thumbnails -._* - -# Files that might appear in the root of a volume -.DocumentRevisions-V100 -.fseventsd -.Spotlight-V100 -.TemporaryItems -.Trashes -.VolumeIcon.icns -.com.apple.timemachine.donotpresent - -# Directories potentially created on remote AFP share -.AppleDB -.AppleDesktop -Network Trash Folder -Temporary Items -.apdisk - -# Windows thumbnail cache files -Thumbs.db -Thumbs.db:encryptable -ehthumbs.db -ehthumbs_vista.db - -# Dump file -*.stackdump - -# Folder config file -[Dd]esktop.ini - -# Recycle Bin used on file shares -$RECYCLE.BIN/ - -# Windows Installer files -*.cab -*.msi -*.msix -*.msm -*.msp - -# Windows shortcuts -*.lnk - -# Generated by Cargo -# will have compiled files and executables -debug/ -target/ - -# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries -# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html -Cargo.lock - -# These are backup files generated by rustfmt -**/*.rs.bk - -# MSVC Windows builds of rustc generate these, which store debugging information -*.pdb - -# Byte-compiled / optimized / DLL files -__pycache__/ -*.py[cod] -*$py.class - -# C extensions -*.so - -# Distribution / packaging -.Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -share/python-wheels/ -tmp/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST - -# PyInstaller -*.manifest -*.spec - -# Installer logs -pip-log.txt -pip-delete-this-directory.txt - -# Unit test / coverage reports -htmlcov/ -.tox/ -.nox/ -.coverage -.coverage.* -.cache -nosetests.xml -coverage.xml -*.cover -*.py,cover -.hypothesis/ -.pytest_cache/ -cover/ - -# Translations -*.mo -*.pot - -# Django stuff: -*.log -local_settings.py -db.sqlite3 -db.sqlite3-journal - -# Flask stuff: -instance/ -.webassets-cache - -# Scrapy stuff: -.scrapy - -# Sphinx documentation -docs/_build/ - -# PyBuilder -.pybuilder/ -target/ - -# Jupyter Notebook -.ipynb_checkpoints - -# IPython -profile_default/ -ipython_config.py - -# pdm -.pdm.toml - -# PEP 582 -__pypackages__/ - -# Celery stuff -celerybeat-schedule -celerybeat.pid - -# SageMath parsed files -*.sage.py - -# Environments -.env -.venv -env/ -venv/ -ENV/ -env.bak/ -venv.bak/ - -# Spyder project settings -.spyderproject -.spyproject - -# Rope project settings -.ropeproject - -# mkdocs documentation -/site - -# mypy -.mypy_cache/ -.dmypy.json -dmypy.json - -# Pyre type checker -.pyre/ - -# pytype static type analyzer -.pytype/ - -# Cython debug symbols -cython_debug/ - -# Poetry local configuration file -poetry.toml - -# ruff -.ruff_cache/ - -# LSP config files -pyrightconfig.json
\ No newline at end of file +/target diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..cb4a9e7 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1705 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "addr2line" +version = "0.24.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dfbe277e56a376000877090da837660b4427aad530e3028d44e0bffe4f89a1c1" +dependencies = [ + "gimli", +] + +[[package]] +name = "adler2" +version = "2.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "512761e0bb2578dd7380c6baaa0f4ce03e84f95e960231d1dec8bf4d7d6e2627" + +[[package]] +name = "aligned-vec" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4aa90d7ce82d4be67b64039a3d588d38dbcc6736577de4a847025ce5b0c468d1" + +[[package]] +name = "anstream" +version = "0.6.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8acc5369981196006228e28809f761875c0327210a891e941f4c683b3a99529b" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55cc3b69f167a1ef2e161439aa98aed94e6028e5f9a59be9a6ffb47aef1651f9" + +[[package]] +name = "anstyle-parse" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca3534e77181a9cc07539ad51f2141fe32f6c3ffd4df76db8ad92346b003ae4e" +dependencies = [ + "anstyle", + "once_cell", + "windows-sys", +] + +[[package]] +name = "anyhow" +version = "1.0.96" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b964d184e89d9b6b67dd2715bc8e74cf3107fb2b529990c90cf517326150bf4" + +[[package]] +name = "arbitrary" +version = "1.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dde20b3d026af13f561bdd0f15edf01fc734f0dafcedbaf42bba506a9517f223" + +[[package]] +name = "arg_enum_proc_macro" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "arrayvec" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50" + +[[package]] +name = "autocfg" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26" + +[[package]] +name = "av1-grain" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6678909d8c5d46a42abcf571271e15fdbc0a225e3646cf23762cd415046c78bf" +dependencies = [ + "anyhow", + "arrayvec", + "log", + "nom", + "num-rational", + "v_frame", +] + +[[package]] +name = "avif-serialize" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e335041290c43101ca215eed6f43ec437eb5a42125573f600fc3fa42b9bddd62" +dependencies = [ + "arrayvec", +] + +[[package]] +name = "backtrace" +version = "0.3.74" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d82cb332cdfaed17ae235a638438ac4d4839913cc2af585c3c6746e8f8bee1a" +dependencies = [ + "addr2line", + "cfg-if", + "libc", + "miniz_oxide", + "object", + "rustc-demangle", + "windows-targets", +] + +[[package]] +name = "backtrace-ext" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "537beee3be4a18fb023b570f80e3ae28003db9167a751266b259926e25539d50" +dependencies = [ + "backtrace", +] + +[[package]] +name = "bit_field" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc827186963e592360843fb5ba4b973e145841266c1357f7180c43526f2e5b61" + +[[package]] +name = "bitflags" +version = "1.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" + +[[package]] +name = "bitflags" +version = "2.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f68f53c83ab957f72c32642f3868eec03eb974d1fb82e453128456482613d36" + +[[package]] +name = "bitstream-io" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6099cdc01846bc367c4e7dd630dc5966dccf36b652fae7a74e17b640411a91b2" + +[[package]] +name = "built" +version = "0.7.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56ed6191a7e78c36abdb16ab65341eefd73d64d303fffccdbb00d51e4205967b" + +[[package]] +name = "bumpalo" +version = "3.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1628fb46dfa0b37568d12e5edd512553eccf6a22a78e8bde00bb4aed84d5bdbf" + +[[package]] +name = "bytemuck" +version = "1.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef657dfab802224e671f5818e9a4935f9b1957ed18e58292690cc39e7a4092a3" + +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + +[[package]] +name = "byteorder-lite" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495" + +[[package]] +name = "cc" +version = "1.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c736e259eea577f443d5c86c304f9f4ae0295c43f3ba05c21f1d66b5f06001af" +dependencies = [ + "jobserver", + "libc", + "shlex", +] + +[[package]] +name = "cfg-expr" +version = "0.15.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02" +dependencies = [ + "smallvec", + "target-lexicon", +] + +[[package]] +name = "cfg-if" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" + +[[package]] +name = "clap" +version = "4.5.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "027bb0d98429ae334a8698531da7077bdf906419543a35a55c2cb1b66437d767" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.5.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5589e0cba072e0f3d23791efac0fd8627b49c829c196a492e88168e6a669d863" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.5.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf4ced95c6f4a675af3da73304b9ac4ed991640c36374e4b46795c49e17cf1ed" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "0.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6" + +[[package]] +name = "color_quant" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b" + +[[package]] +name = "colorchoice" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990" + +[[package]] +name = "console" +version = "0.15.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "054ccb5b10f9f2cbf51eb355ca1d05c2d279ce1804688d0db74b4733a5aeafd8" +dependencies = [ + "encode_unicode", + "libc", + "once_cell", + "unicode-width 0.2.0", + "windows-sys", +] + +[[package]] +name = "crc32fast" +version = "1.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a97769d94ddab943e4510d138150169a2758b5ef3eb191a9ee688de3e23ef7b3" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "crossbeam-deque" +version = "0.8.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51" +dependencies = [ + "crossbeam-epoch", + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-epoch" +version = "0.9.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28" + +[[package]] +name = "crunchy" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43da5946c66ffcc7745f48db692ffbb10a83bfe0afd96235c5c2a4fb23994929" + +[[package]] +name = "dialoguer" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "658bce805d770f407bc62102fca7c2c64ceef2fbcb2b8bd19d2765ce093980de" +dependencies = [ + "console", + "shell-words", + "tempfile", + "thiserror 1.0.69", + "zeroize", +] + +[[package]] +name = "either" +version = "1.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60b1af1c220855b6ceac025d3f6ecdd2b7c4894bfe9cd9bda4fbb4bc7c0d4cf0" + +[[package]] +name = "encode_unicode" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0" + +[[package]] +name = "equivalent" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" + +[[package]] +name = "errno" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33d852cb9b869c2a9b3df2f71a3074817f01e1844f839a144f5fcef059a4eb5d" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "exr" +version = "1.73.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f83197f59927b46c04a183a619b7c29df34e63e63c7869320862268c0ef687e0" +dependencies = [ + "bit_field", + "half", + "lebe", + "miniz_oxide", + "rayon-core", + "smallvec", + "zune-inflate", +] + +[[package]] +name = "fastrand" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be" + +[[package]] +name = "fdeflate" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c" +dependencies = [ + "simd-adler32", +] + +[[package]] +name = "flate2" +version = "1.0.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c936bfdafb507ebbf50b8074c54fa31c5be9a1e7e5f467dd659697041407d07c" +dependencies = [ + "crc32fast", + "miniz_oxide", +] + +[[package]] +name = "fuchsia-cprng" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a06f77d526c1a601b7c4cdd98f54b5eaabffc14d5f2f0296febdc7f357c6d3ba" + +[[package]] +name = "getrandom" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7" +dependencies = [ + "cfg-if", + "libc", + "wasi 0.11.0+wasi-snapshot-preview1", +] + +[[package]] +name = "getrandom" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43a49c392881ce6d5c3b8cb70f98717b7c07aabbdff06687b9030dbfbe2725f8" +dependencies = [ + "cfg-if", + "libc", + "wasi 0.13.3+wasi-0.2.2", + "windows-targets", +] + +[[package]] +name = "gif" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3fb2d69b19215e18bb912fa30f7ce15846e301408695e44e0ef719f1da9e19f2" +dependencies = [ + "color_quant", + "weezl", +] + +[[package]] +name = "gimli" +version = "0.31.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f" + +[[package]] +name = "half" +version = "2.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dd08c532ae367adf81c312a4580bc67f1d0fe8bc9c460520283f4c0ff277888" +dependencies = [ + "cfg-if", + "crunchy", +] + +[[package]] +name = "hashbrown" +version = "0.15.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf151400ff0baff5465007dd2f3e717f3fe502074ca563069ce3a6629d07b289" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "image" +version = "0.25.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd6f44aed642f18953a158afeb30206f4d50da59fbc66ecb53c66488de73563b" +dependencies = [ + "bytemuck", + "byteorder-lite", + "color_quant", + "exr", + "gif", + "image-webp", + "num-traits", + "png", + "qoi", + "ravif", + "rayon", + "rgb", + "tiff", + "zune-core", + "zune-jpeg", +] + +[[package]] +name = "image-webp" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b77d01e822461baa8409e156015a1d91735549f0f2c17691bd2d996bef238f7f" +dependencies = [ + "byteorder-lite", + "quick-error", +] + +[[package]] +name = "imgref" +version = "1.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0263a3d970d5c054ed9312c0057b4f3bde9c0b33836d3637361d4a9e6e7a408" + +[[package]] +name = "indexmap" +version = "2.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c9c992b02b5b4c94ea26e32fe5bccb7aa7d9f390ab5c1221ff895bc7ea8b652" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "indicatif" +version = "0.17.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "183b3088984b400f4cfac3620d5e076c84da5364016b4f49473de574b2586235" +dependencies = [ + "console", + "number_prefix", + "portable-atomic", + "unicode-width 0.2.0", + "web-time", +] + +[[package]] +name = "interpolate_name" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "is_ci" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7655c9839580ee829dfacba1d1278c2b7883e50a277ff7541299489d6bdfdc45" + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf" + +[[package]] +name = "itertools" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba291022dbbd398a455acf126c1e341954079855bc60dfdda641363bd6922569" +dependencies = [ + "either", +] + +[[package]] +name = "itoa" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d75a2a4b1b190afb6f5425f10f6a8f959d2ea0b9c2b1d79553551850539e4674" + +[[package]] +name = "jobserver" +version = "0.1.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48d1dbcbbeb6a7fec7e059840aa538bd62aaccf972c7346c4d9d2059312853d0" +dependencies = [ + "libc", +] + +[[package]] +name = "jpeg-decoder" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5d4a7da358eff58addd2877a45865158f0d78c911d43a5784ceb7bbf52833b0" + +[[package]] +name = "js-sys" +version = "0.3.77" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1cfaf33c695fc6e08064efbc1f72ec937429614f25eef83af942d0e227c3a28f" +dependencies = [ + "once_cell", + "wasm-bindgen", +] + +[[package]] +name = "lebe" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03087c2bad5e1034e8cace5926dec053fb3790248370865f5117a7d0213354c8" + +[[package]] +name = "libc" +version = "0.2.170" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "875b3680cb2f8f71bdcf9a30f38d48282f5d3c95cbf9b3fa57269bb5d5c06828" + +[[package]] +name = "libfuzzer-sys" +version = "0.4.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf78f52d400cf2d84a3a973a78a592b4adc535739e0a5597a0da6f0c357adc75" +dependencies = [ + "arbitrary", + "cc", +] + +[[package]] +name = "libnres" +version = "0.1.4" +dependencies = [ + "byteorder", + "log", + "miette", + "thiserror 2.0.11", +] + +[[package]] +name = "linux-raw-sys" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab" + +[[package]] +name = "log" +version = "0.4.26" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30bde2b3dc3671ae49d8e2e9f044c7c005836e7a023ee57cffa25ab82764bb9e" + +[[package]] +name = "loop9" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fae87c125b03c1d2c0150c90365d7d6bcc53fb73a9acaef207d2d065860f062" +dependencies = [ + "imgref", +] + +[[package]] +name = "maybe-rayon" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ea1f30cedd69f0a2954655f7188c6a834246d2bcf1e315e2ac40c4b24dc9519" +dependencies = [ + "cfg-if", + "rayon", +] + +[[package]] +name = "memchr" +version = "2.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3" + +[[package]] +name = "miette" +version = "7.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a955165f87b37fd1862df2a59547ac542c77ef6d17c666f619d1ad22dd89484" +dependencies = [ + "backtrace", + "backtrace-ext", + "cfg-if", + "miette-derive", + "owo-colors", + "supports-color", + "supports-hyperlinks", + "supports-unicode", + "terminal_size", + "textwrap", + "thiserror 1.0.69", + "unicode-width 0.1.14", +] + +[[package]] +name = "miette-derive" +version = "7.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf45bf44ab49be92fd1227a3be6fc6f617f1a337c06af54981048574d8783147" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "minimal-lexical" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a" + +[[package]] +name = "miniz_oxide" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e3e04debbb59698c15bacbb6d93584a8c0ca9cc3213cb423d31f760d8843ce5" +dependencies = [ + "adler2", + "simd-adler32", +] + +[[package]] +name = "new_debug_unreachable" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086" + +[[package]] +name = "nom" +version = "7.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a" +dependencies = [ + "memchr", + "minimal-lexical", +] + +[[package]] +name = "noop_proc_macro" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0676bb32a98c1a483ce53e500a81ad9c3d5b3f7c920c28c24e9cb0980d0b5bc8" + +[[package]] +name = "nres-cli" +version = "0.2.3" +dependencies = [ + "byteorder", + "clap", + "console", + "dialoguer", + "indicatif", + "libnres", + "miette", + "tempdir", +] + +[[package]] +name = "num-bigint" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-derive" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "num-integer" +version = "0.1.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-rational" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824" +dependencies = [ + "num-bigint", + "num-integer", + "num-traits", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "number_prefix" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "830b246a0e5f20af87141b25c173cd1b609bd7779a4617d6ec582abaf90870f3" + +[[package]] +name = "object" +version = "0.36.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "62948e14d923ea95ea2c7c86c71013138b66525b86bdc08d2dcc262bdb497b87" +dependencies = [ + "memchr", +] + +[[package]] +name = "once_cell" +version = "1.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "945462a4b81e43c4e3ba96bd7b49d834c6f61198356aa858733bc4acf3cbe62e" + +[[package]] +name = "owo-colors" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1036865bb9422d3300cf723f657c2851d0e9ab12567854b1f4eba3d77decf564" + +[[package]] +name = "packer" +version = "0.1.0" +dependencies = [ + "byteorder", + "serde", + "serde_json", +] + +[[package]] +name = "paste" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a" + +[[package]] +name = "pkg-config" +version = "0.3.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "953ec861398dccce10c670dfeaf3ec4911ca479e9c02154b3a215178c5f566f2" + +[[package]] +name = "png" +version = "0.17.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526" +dependencies = [ + "bitflags 1.3.2", + "crc32fast", + "fdeflate", + "flate2", + "miniz_oxide", +] + +[[package]] +name = "portable-atomic" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "280dc24453071f1b63954171985a0b0d30058d287960968b9b2aca264c8d4ee6" + +[[package]] +name = "ppv-lite86" +version = "0.2.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77957b295656769bb8ad2b6a6b09d897d94f05c41b069aede1fcdaa675eaea04" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "proc-macro2" +version = "1.0.93" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60946a68e5f9d28b0dc1c21bb8a97ee7d018a8b322fa57838ba31cc878e22d99" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "profiling" +version = "1.0.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "afbdc74edc00b6f6a218ca6a5364d6226a259d4b8ea1af4a0ea063f27e179f4d" +dependencies = [ + "profiling-procmacros", +] + +[[package]] +name = "profiling-procmacros" +version = "1.0.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a65f2e60fbf1063868558d69c6beacf412dc755f9fc020f514b7955fc914fe30" +dependencies = [ + "quote", + "syn", +] + +[[package]] +name = "qoi" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f6d64c71eb498fe9eae14ce4ec935c555749aef511cca85b5568910d6e48001" +dependencies = [ + "bytemuck", +] + +[[package]] +name = "quick-error" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3" + +[[package]] +name = "quote" +version = "1.0.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e4dccaaaf89514f546c693ddc140f729f958c247918a13380cccc6078391acc" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "rand" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "552840b97013b1a26992c11eac34bdd778e464601a4c2054b5f0bff7c6761293" +dependencies = [ + "fuchsia-cprng", + "libc", + "rand_core 0.3.1", + "rdrand", + "winapi", +] + +[[package]] +name = "rand" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" +dependencies = [ + "libc", + "rand_chacha", + "rand_core 0.6.4", +] + +[[package]] +name = "rand_chacha" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" +dependencies = [ + "ppv-lite86", + "rand_core 0.6.4", +] + +[[package]] +name = "rand_core" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7a6fdeb83b075e8266dcc8762c22776f6877a63111121f5f8c7411e5be7eed4b" +dependencies = [ + "rand_core 0.4.2", +] + +[[package]] +name = "rand_core" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c33a3c44ca05fa6f1807d8e6743f3824e8509beca625669633be0acbdf509dc" + +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.15", +] + +[[package]] +name = "rav1e" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd87ce80a7665b1cce111f8a16c1f3929f6547ce91ade6addf4ec86a8dda5ce9" +dependencies = [ + "arbitrary", + "arg_enum_proc_macro", + "arrayvec", + "av1-grain", + "bitstream-io", + "built", + "cfg-if", + "interpolate_name", + "itertools", + "libc", + "libfuzzer-sys", + "log", + "maybe-rayon", + "new_debug_unreachable", + "noop_proc_macro", + "num-derive", + "num-traits", + "once_cell", + "paste", + "profiling", + "rand 0.8.5", + "rand_chacha", + "simd_helpers", + "system-deps", + "thiserror 1.0.69", + "v_frame", + "wasm-bindgen", +] + +[[package]] +name = "ravif" +version = "0.11.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2413fd96bd0ea5cdeeb37eaf446a22e6ed7b981d792828721e74ded1980a45c6" +dependencies = [ + "avif-serialize", + "imgref", + "loop9", + "quick-error", + "rav1e", + "rayon", + "rgb", +] + +[[package]] +name = "rayon" +version = "1.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b418a60154510ca1a002a752ca9714984e21e4241e804d32555251faf8b78ffa" +dependencies = [ + "either", + "rayon-core", +] + +[[package]] +name = "rayon-core" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1465873a3dfdaa8ae7cb14b4383657caab0b3e8a0aa9ae8e04b044854c8dfce2" +dependencies = [ + "crossbeam-deque", + "crossbeam-utils", +] + +[[package]] +name = "rdrand" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "678054eb77286b51581ba43620cc911abf02758c91f93f479767aed0f90458b2" +dependencies = [ + "rand_core 0.3.1", +] + +[[package]] +name = "remove_dir_all" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3acd125665422973a33ac9d3dd2df85edad0f4ae9b00dafb1a05e43a9f5ef8e7" +dependencies = [ + "winapi", +] + +[[package]] +name = "rgb" +version = "0.8.50" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57397d16646700483b67d2dd6511d79318f9d057fdbd21a4066aeac8b41d310a" + +[[package]] +name = "rustc-demangle" +version = "0.1.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "719b953e2095829ee67db738b3bfa9fa368c94900df327b3f07fe6e794d2fe1f" + +[[package]] +name = "rustix" +version = "0.38.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154" +dependencies = [ + "bitflags 2.8.0", + "errno", + "libc", + "linux-raw-sys", + "windows-sys", +] + +[[package]] +name = "rustversion" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f7c45b9784283f1b2e7fb61b42047c2fd678ef0960d4f6f1eba131594cc369d4" + +[[package]] +name = "ryu" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ea1a2d0a644769cc99faa24c3ad26b379b786fe7c36fd3c546254801650e6dd" + +[[package]] +name = "serde" +version = "1.0.218" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8dfc9d19bdbf6d17e22319da49161d5d0108e4188e8b680aef6299eed22df60" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.218" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f09503e191f4e797cb8aac08e9a4a4695c5edf6a2e70e376d961ddd5c969f82b" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.139" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "44f86c3acccc9c65b153fe1b85a3be07fe5515274ec9f0653b4a0875731c72a6" +dependencies = [ + "itoa", + "memchr", + "ryu", + "serde", +] + +[[package]] +name = "serde_spanned" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "87607cb1398ed59d48732e575a4c28a7a8ebf2454b964fe3f224f2afc07909e1" +dependencies = [ + "serde", +] + +[[package]] +name = "shell-words" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24188a676b6ae68c3b2cb3a01be17fbf7240ce009799bb56d5b1409051e78fde" + +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + +[[package]] +name = "simd-adler32" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d66dc143e6b11c1eddc06d5c423cfc97062865baf299914ab64caa38182078fe" + +[[package]] +name = "simd_helpers" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95890f873bec569a0362c235787f3aca6e1e887302ba4840839bcc6459c42da6" +dependencies = [ + "quote", +] + +[[package]] +name = "smallvec" +version = "1.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fcf8323ef1faaee30a44a340193b1ac6814fd9b7b4e88e9d4519a3e4abe1cfd" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "supports-color" +version = "3.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c64fc7232dd8d2e4ac5ce4ef302b1d81e0b80d055b9d77c7c4f51f6aa4c867d6" +dependencies = [ + "is_ci", +] + +[[package]] +name = "supports-hyperlinks" +version = "3.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "804f44ed3c63152de6a9f90acbea1a110441de43006ea51bcce8f436196a288b" + +[[package]] +name = "supports-unicode" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7401a30af6cb5818bb64852270bb722533397edcfc7344954a38f420819ece2" + +[[package]] +name = "syn" +version = "2.0.98" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36147f1a48ae0ec2b5b3bc5b537d267457555a10dc06f3dbc8cb11ba3006d3b1" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "system-deps" +version = "6.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a3e535eb8dded36d55ec13eddacd30dec501792ff23a0b1682c38601b8cf2349" +dependencies = [ + "cfg-expr", + "heck", + "pkg-config", + "toml", + "version-compare", +] + +[[package]] +name = "target-lexicon" +version = "0.12.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" + +[[package]] +name = "tempdir" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15f2b5fb00ccdf689e0149d1b1b3c03fead81c2b37735d812fa8bddbbf41b6d8" +dependencies = [ + "rand 0.4.6", + "remove_dir_all", +] + +[[package]] +name = "tempfile" +version = "3.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22e5a0acb1f3f55f65cc4a866c361b2fb2a0ff6366785ae6fbb5f85df07ba230" +dependencies = [ + "cfg-if", + "fastrand", + "getrandom 0.3.1", + "once_cell", + "rustix", + "windows-sys", +] + +[[package]] +name = "terminal_size" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5352447f921fda68cf61b4101566c0bdb5104eff6804d0678e5227580ab6a4e9" +dependencies = [ + "rustix", + "windows-sys", +] + +[[package]] +name = "texture-decoder" +version = "0.1.0" +dependencies = [ + "byteorder", + "image", +] + +[[package]] +name = "textwrap" +version = "0.16.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23d434d3f8967a09480fb04132ebe0a3e088c173e6d0ee7897abbdf4eab0f8b9" +dependencies = [ + "unicode-linebreak", + "unicode-width 0.1.14", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", +] + +[[package]] +name = "thiserror" +version = "2.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d452f284b73e6d76dd36758a0c8684b1d5be31f92b89d07fd5822175732206fc" +dependencies = [ + "thiserror-impl 2.0.11", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26afc1baea8a989337eeb52b6e72a039780ce45c3edfcc9c5b9d112feeb173c2" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tiff" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba1310fcea54c6a9a4fd1aad794ecc02c31682f6bfbecdf460bf19533eed1e3e" +dependencies = [ + "flate2", + "jpeg-decoder", + "weezl", +] + +[[package]] +name = "toml" +version = "0.8.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd87a5cdd6ffab733b2f74bc4fd7ee5fff6634124999ac278c35fc78c6120148" +dependencies = [ + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", +] + +[[package]] +name = "toml_datetime" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0dd7358ecb8fc2f8d014bf86f6f638ce72ba252a2c3a2572f2a795f1d23efb41" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_edit" +version = "0.22.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "17b4795ff5edd201c7cd6dca065ae59972ce77d1b80fa0a84d94950ece7d1474" +dependencies = [ + "indexmap", + "serde", + "serde_spanned", + "toml_datetime", + "winnow", +] + +[[package]] +name = "unicode-ident" +version = "1.0.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00e2473a93778eb0bad35909dff6a10d28e63f792f16ed15e404fca9d5eeedbe" + +[[package]] +name = "unicode-linebreak" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f" + +[[package]] +name = "unicode-width" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af" + +[[package]] +name = "unicode-width" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd" + +[[package]] +name = "unpacker" +version = "0.1.1" +dependencies = [ + "byteorder", + "serde", + "serde_json", +] + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "v_frame" +version = "0.3.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f32aaa24bacd11e488aa9ba66369c7cd514885742c9fe08cfe85884db3e92b" +dependencies = [ + "aligned-vec", + "num-traits", + "wasm-bindgen", +] + +[[package]] +name = "version-compare" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "852e951cb7832cb45cb1169900d19760cfa39b82bc0ea9c0e5a14ae88411c98b" + +[[package]] +name = "wasi" +version = "0.11.0+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423" + +[[package]] +name = "wasi" +version = "0.13.3+wasi-0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26816d2e1a4a36a2940b96c5296ce403917633dff8f3440e9b236ed6f6bacad2" +dependencies = [ + "wit-bindgen-rt", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1edc8929d7499fc4e8f0be2262a241556cfc54a0bea223790e71446f2aab1ef5" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", +] + +[[package]] +name = "wasm-bindgen-backend" +version = "0.2.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f0a0651a5c2bc21487bde11ee802ccaf4c51935d0d3d42a6101f98161700bc6" +dependencies = [ + "bumpalo", + "log", + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fe63fc6d09ed3792bd0897b314f53de8e16568c2b3f7982f468c0bf9bd0b407" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ae87ea40c9f689fc23f209965b6fb8a99ad69aeeb0231408be24920604395de" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-backend", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.100" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a05d73b933a847d6cccdda8f838a22ff101ad9bf93e33684f39c1f5f0eece3d" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "weezl" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53a85b86a771b1c87058196170769dd264f66c0782acf1ae6cc51bfd64b39082" + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" + +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "winnow" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e7f4ea97f6f78012141bcdb6a216b2609f0979ada50b20ca5b52dde2eac2bb1" +dependencies = [ + "memchr", +] + +[[package]] +name = "wit-bindgen-rt" +version = "0.33.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3268f3d866458b787f390cf61f4bbb563b922d091359f9608842999eaee3943c" +dependencies = [ + "bitflags 2.8.0", +] + +[[package]] +name = "zerocopy" +version = "0.7.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b9b4fd18abc82b8136838da5d50bae7bdea537c574d8dc1a34ed098d6c166f0" +dependencies = [ + "byteorder", + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.7.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa4f8080344d4671fb4e831a13ad1e68092748387dfc4f55e356242fae12ce3e" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zeroize" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde" + +[[package]] +name = "zune-core" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f423a2c17029964870cfaabb1f13dfab7d092a62a29a89264f4d36990ca414a" + +[[package]] +name = "zune-inflate" +version = "0.2.54" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73ab332fe2f6680068f3582b16a24f90ad7096d5d39b974d1c0aff0125116f02" +dependencies = [ + "simd-adler32", +] + +[[package]] +name = "zune-jpeg" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "99a5bab8d7dedf81405c4bb1f2b83ea057643d9cb28778cea9eecddeedd2e028" +dependencies = [ + "zune-core", +] @@ -1,6 +1,12 @@ [workspace] -resolver = "3" -members = ["crates/*"] +resolver = "2" +members = [ + "libnres", + "nres-cli", + "packer", + "texture-decoder", + "unpacker", +] [profile.release] codegen-units = 1 @@ -1,55 +1,11 @@ -# FParkan +# Utilities for the game "Parkan: Iron Strategy" -Open source проект с реализацией компонентов игрового движка игры **«Паркан: Железная Стратегия»** и набором [вспомогательных инструментов](tools) для исследования. +This repository contains utilities, tools, and libraries for the game "Parkan: Iron Strategy." -## Описание +## List of projects -Проект находится в активной разработке и включает: - -- библиотеки для работы с форматами игровых архивов; -- инструменты для валидации/подготовки тестовых данных; -- спецификации форматов и сопутствующую документацию. - -## Установка - -Проект находится в начальной стадии, подробная инструкция по установке пока отсутствует. - -## Документация - -- локально: каталог [`docs/`](docs) -- сайт: <https://fparkan.popov.link> - -## Инструменты - -Вспомогательные инструменты находятся в каталоге [`tools/`](tools). - -- [tools/archive_roundtrip_validator.py](tools/archive_roundtrip_validator.py) — инструмент верификации документации по архивам `NRes`/`RsLi` на реальных файлах (включая `unpack -> repack -> byte-compare`). -- [tools/init_testdata.py](tools/init_testdata.py) — подготовка тестовых данных по сигнатурам с раскладкой по каталогам. - -## Библиотеки - -- [crates/nres](crates/nres) — библиотека для работы с файлами архивов NRes (чтение, поиск, редактирование, сохранение). -- [crates/rsli](crates/rsli) — библиотека для работы с файлами архивов RsLi (чтение, поиск, загрузка/распаковка поддерживаемых методов). - -## Тестирование - -Базовое тестирование проходит на синтетических тестах из репозитория. - -Для дополнительного тестирования на реальных игровых ресурсах: - -- используйте [tools/init_testdata.py](tools/init_testdata.py) для подготовки локального набора; -- используйте оригинальную копию игры (диск или [GOG-версия](https://www.gog.com/en/game/parkan_iron_strategy)); -- игровые ресурсы в репозиторий не включаются, так как защищены авторским правом. - -## Contributing & Support - -Проект активно поддерживается и открыт для contribution. Issues и pull requests можно создавать в обоих репозиториях: - -- **Primary development**: [valentineus/fparkan](https://code.popov.link/valentineus/fparkan) -- **GitHub mirror**: [valentineus/fparkan](https://github.com/valentineus/fparkan) - -Основная разработка ведётся в self-hosted репозитории. - -## Лицензия - -Проект распространяется под лицензией **[GNU GPL v2](LICENSE.txt)**. +- [unpacker](unpacker): Text-based utility for unpacking game resources in the NRres format. Allows unpacking 100% of game resources. +- [packer](packer): Text-based utility for packing game resources in the NRres format. Allows packing 100% of game resources. +- [texture-decoder](texture-decoder): (WIP) Decoder for game textures. Decodes approximately 20% of game textures. +- [libnres](libnres): _(Deprecation)_ Library for NRes files. +- [nres-cli](nres-cli): _(Deprecation)_ Console tool for NRes files. diff --git a/crates/common/Cargo.toml b/crates/common/Cargo.toml deleted file mode 100644 index e020b17..0000000 --- a/crates/common/Cargo.toml +++ /dev/null @@ -1,6 +0,0 @@ -[package] -name = "common" -version = "0.1.0" -edition = "2021" - -[dependencies] diff --git a/crates/common/src/lib.rs b/crates/common/src/lib.rs deleted file mode 100644 index 69796d3..0000000 --- a/crates/common/src/lib.rs +++ /dev/null @@ -1,44 +0,0 @@ -use std::io; - -/// Resource payload that can be either borrowed from mapped bytes or owned. -#[derive(Clone, Debug)] -pub enum ResourceData<'a> { - Borrowed(&'a [u8]), - Owned(Vec<u8>), -} - -impl<'a> ResourceData<'a> { - pub fn as_slice(&self) -> &[u8] { - match self { - Self::Borrowed(slice) => slice, - Self::Owned(buf) => buf.as_slice(), - } - } - - pub fn into_owned(self) -> Vec<u8> { - match self { - Self::Borrowed(slice) => slice.to_vec(), - Self::Owned(buf) => buf, - } - } -} - -impl AsRef<[u8]> for ResourceData<'_> { - fn as_ref(&self) -> &[u8] { - self.as_slice() - } -} - -/// Output sink used by `read_into`/`load_into` APIs. -pub trait OutputBuffer { - /// Writes the full payload to the sink, replacing any previous content. - fn write_exact(&mut self, data: &[u8]) -> io::Result<()>; -} - -impl OutputBuffer for Vec<u8> { - fn write_exact(&mut self, data: &[u8]) -> io::Result<()> { - self.clear(); - self.extend_from_slice(data); - Ok(()) - } -} diff --git a/crates/nres/Cargo.toml b/crates/nres/Cargo.toml deleted file mode 100644 index 38b8822..0000000 --- a/crates/nres/Cargo.toml +++ /dev/null @@ -1,10 +0,0 @@ -[package] -name = "nres" -version = "0.1.0" -edition = "2021" - -[dependencies] -common = { path = "../common" } - -[target.'cfg(windows)'.dependencies] -windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] } diff --git a/crates/nres/README.md b/crates/nres/README.md deleted file mode 100644 index 8b9dfb5..0000000 --- a/crates/nres/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# nres - -Rust-библиотека для работы с архивами формата **NRes**. - -## Что умеет - -- Открытие архива из файла (`open_path`) и из памяти (`open_bytes`). -- Поддержка `raw_mode` (весь файл как единый ресурс). -- Чтение метаданных и итерация по записям. -- Поиск по имени без учёта регистра (`find`). -- Чтение данных ресурса (`read`, `read_into`, `raw_slice`). -- Редактирование архива через `Editor`: -- `add`, `replace_data`, `remove`. -- `commit` с пересчётом `sort_index`, выравниванием по 8 байт и атомарной записью файла. - -## Модель ошибок - -Библиотека возвращает типизированные ошибки (`InvalidMagic`, `UnsupportedVersion`, `TotalSizeMismatch`, `DirectoryOutOfBounds`, `EntryDataOutOfBounds`, и др.) без паник в production-коде. - -## Покрытие тестами - -### Реальные файлы - -- Рекурсивный прогон по `testdata/nres/**`. -- Сейчас в наборе: **120 архивов**. -- Для каждого архива проверяется: -- чтение всех записей; -- `read`/`read_into`/`raw_slice`; -- `find`; -- `unpack -> repack (Editor::commit)` с проверкой **byte-to-byte**. - -### Синтетические тесты - -- Проверка основных сценариев редактирования (`add/replace/remove/commit`). -- Проверка валидации и ошибок: -- `InvalidMagic`, `UnsupportedVersion`, `TotalSizeMismatch`, `InvalidEntryCount`, `DirectoryOutOfBounds`, `NameTooLong`, `EntryDataOutOfBounds`, `EntryIdOutOfRange`, `NameContainsNul`. - -## Быстрый запуск тестов - -```bash -cargo test -p nres -- --nocapture -``` diff --git a/crates/nres/src/error.rs b/crates/nres/src/error.rs deleted file mode 100644 index 9a3c651..0000000 --- a/crates/nres/src/error.rs +++ /dev/null @@ -1,110 +0,0 @@ -use core::fmt; - -#[derive(Debug)] -#[non_exhaustive] -pub enum Error { - Io(std::io::Error), - - InvalidMagic { - got: [u8; 4], - }, - UnsupportedVersion { - got: u32, - }, - TotalSizeMismatch { - header: u32, - actual: u64, - }, - - InvalidEntryCount { - got: i32, - }, - TooManyEntries { - got: usize, - }, - DirectoryOutOfBounds { - directory_offset: u64, - directory_len: u64, - file_len: u64, - }, - - EntryIdOutOfRange { - id: u32, - entry_count: u32, - }, - EntryDataOutOfBounds { - id: u32, - offset: u64, - size: u32, - directory_offset: u64, - }, - NameTooLong { - got: usize, - max: usize, - }, - NameContainsNul, - BadNameEncoding, - - IntegerOverflow, - - RawModeDisallowsOperation(&'static str), -} - -impl From<std::io::Error> for Error { - fn from(value: std::io::Error) -> Self { - Self::Io(value) - } -} - -impl fmt::Display for Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - Error::Io(e) => write!(f, "I/O error: {e}"), - Error::InvalidMagic { got } => write!(f, "invalid NRes magic: {got:02X?}"), - Error::UnsupportedVersion { got } => { - write!(f, "unsupported NRes version: {got:#x}") - } - Error::TotalSizeMismatch { header, actual } => { - write!(f, "NRes total_size mismatch: header={header}, actual={actual}") - } - Error::InvalidEntryCount { got } => write!(f, "invalid entry_count: {got}"), - Error::TooManyEntries { got } => write!(f, "too many entries: {got} exceeds u32::MAX"), - Error::DirectoryOutOfBounds { - directory_offset, - directory_len, - file_len, - } => write!( - f, - "directory out of bounds: off={directory_offset}, len={directory_len}, file={file_len}" - ), - Error::EntryIdOutOfRange { id, entry_count } => { - write!(f, "entry id out of range: id={id}, count={entry_count}") - } - Error::EntryDataOutOfBounds { - id, - offset, - size, - directory_offset, - } => write!( - f, - "entry data out of bounds: id={id}, off={offset}, size={size}, dir_off={directory_offset}" - ), - Error::NameTooLong { got, max } => write!(f, "name too long: {got} > {max}"), - Error::NameContainsNul => write!(f, "name contains NUL byte"), - Error::BadNameEncoding => write!(f, "bad name encoding"), - Error::IntegerOverflow => write!(f, "integer overflow"), - Error::RawModeDisallowsOperation(op) => { - write!(f, "operation not allowed in raw mode: {op}") - } - } - } -} - -impl std::error::Error for Error { - fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { - match self { - Self::Io(err) => Some(err), - _ => None, - } - } -} diff --git a/crates/nres/src/lib.rs b/crates/nres/src/lib.rs deleted file mode 100644 index e0631e3..0000000 --- a/crates/nres/src/lib.rs +++ /dev/null @@ -1,702 +0,0 @@ -pub mod error; - -use crate::error::Error; -use common::{OutputBuffer, ResourceData}; -use core::ops::Range; -use std::cmp::Ordering; -use std::fs::{self, OpenOptions as FsOpenOptions}; -use std::io::Write; -use std::path::{Path, PathBuf}; -use std::sync::Arc; -use std::time::{SystemTime, UNIX_EPOCH}; - -pub type Result<T> = core::result::Result<T, Error>; - -#[derive(Clone, Debug, Default)] -pub struct OpenOptions { - pub raw_mode: bool, - pub sequential_hint: bool, - pub prefetch_pages: bool, -} - -#[derive(Clone, Debug, Default)] -pub enum OpenMode { - #[default] - ReadOnly, - ReadWrite, -} - -#[derive(Debug)] -pub struct Archive { - bytes: Arc<[u8]>, - entries: Vec<EntryRecord>, - raw_mode: bool, -} - -#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -pub struct EntryId(pub u32); - -#[derive(Clone, Debug)] -pub struct EntryMeta { - pub kind: u32, - pub attr1: u32, - pub attr2: u32, - pub attr3: u32, - pub name: String, - pub data_offset: u64, - pub data_size: u32, - pub sort_index: u32, -} - -#[derive(Copy, Clone, Debug)] -pub struct EntryRef<'a> { - pub id: EntryId, - pub meta: &'a EntryMeta, -} - -#[derive(Clone, Debug)] -struct EntryRecord { - meta: EntryMeta, - name_raw: [u8; 36], -} - -impl Archive { - pub fn open_path(path: impl AsRef<Path>) -> Result<Self> { - Self::open_path_with(path, OpenMode::ReadOnly, OpenOptions::default()) - } - - pub fn open_path_with( - path: impl AsRef<Path>, - _mode: OpenMode, - opts: OpenOptions, - ) -> Result<Self> { - let bytes = fs::read(path.as_ref())?; - let arc: Arc<[u8]> = Arc::from(bytes.into_boxed_slice()); - Self::open_bytes(arc, opts) - } - - pub fn open_bytes(bytes: Arc<[u8]>, opts: OpenOptions) -> Result<Self> { - let (entries, _) = parse_archive(&bytes, opts.raw_mode)?; - if opts.prefetch_pages { - prefetch_pages(&bytes); - } - Ok(Self { - bytes, - entries, - raw_mode: opts.raw_mode, - }) - } - - pub fn entry_count(&self) -> usize { - self.entries.len() - } - - pub fn entries(&self) -> impl Iterator<Item = EntryRef<'_>> { - self.entries - .iter() - .enumerate() - .map(|(idx, entry)| EntryRef { - id: EntryId(u32::try_from(idx).expect("entry count validated at parse")), - meta: &entry.meta, - }) - } - - pub fn find(&self, name: &str) -> Option<EntryId> { - if self.entries.is_empty() { - return None; - } - - if !self.raw_mode { - let mut low = 0usize; - let mut high = self.entries.len(); - while low < high { - let mid = low + (high - low) / 2; - let Ok(target_idx) = usize::try_from(self.entries[mid].meta.sort_index) else { - break; - }; - if target_idx >= self.entries.len() { - break; - } - let cmp = cmp_name_case_insensitive( - name.as_bytes(), - entry_name_bytes(&self.entries[target_idx].name_raw), - ); - match cmp { - Ordering::Less => high = mid, - Ordering::Greater => low = mid + 1, - Ordering::Equal => { - return Some(EntryId( - u32::try_from(target_idx).expect("entry count validated at parse"), - )) - } - } - } - } - - self.entries.iter().enumerate().find_map(|(idx, entry)| { - if cmp_name_case_insensitive(name.as_bytes(), entry_name_bytes(&entry.name_raw)) - == Ordering::Equal - { - Some(EntryId( - u32::try_from(idx).expect("entry count validated at parse"), - )) - } else { - None - } - }) - } - - pub fn get(&self, id: EntryId) -> Option<EntryRef<'_>> { - let idx = usize::try_from(id.0).ok()?; - let entry = self.entries.get(idx)?; - Some(EntryRef { - id, - meta: &entry.meta, - }) - } - - pub fn read(&self, id: EntryId) -> Result<ResourceData<'_>> { - let range = self.entry_range(id)?; - Ok(ResourceData::Borrowed(&self.bytes[range])) - } - - pub fn read_into(&self, id: EntryId, out: &mut dyn OutputBuffer) -> Result<usize> { - let range = self.entry_range(id)?; - out.write_exact(&self.bytes[range.clone()])?; - Ok(range.len()) - } - - pub fn raw_slice(&self, id: EntryId) -> Result<Option<&[u8]>> { - let range = self.entry_range(id)?; - Ok(Some(&self.bytes[range])) - } - - pub fn edit_path(path: impl AsRef<Path>) -> Result<Editor> { - let path_buf = path.as_ref().to_path_buf(); - let bytes = fs::read(&path_buf)?; - let arc: Arc<[u8]> = Arc::from(bytes.into_boxed_slice()); - let (entries, _) = parse_archive(&arc, false)?; - let mut editable = Vec::with_capacity(entries.len()); - for entry in &entries { - let range = checked_range(entry.meta.data_offset, entry.meta.data_size, arc.len())?; - editable.push(EditableEntry { - meta: entry.meta.clone(), - name_raw: entry.name_raw, - data: EntryData::Borrowed(range), // Copy-on-write: only store range - }); - } - Ok(Editor { - path: path_buf, - source: arc, - entries: editable, - }) - } - - fn entry_range(&self, id: EntryId) -> Result<Range<usize>> { - let idx = usize::try_from(id.0).map_err(|_| Error::IntegerOverflow)?; - let Some(entry) = self.entries.get(idx) else { - return Err(Error::EntryIdOutOfRange { - id: id.0, - entry_count: self.entries.len().try_into().unwrap_or(u32::MAX), - }); - }; - checked_range( - entry.meta.data_offset, - entry.meta.data_size, - self.bytes.len(), - ) - } -} - -pub struct Editor { - path: PathBuf, - source: Arc<[u8]>, - entries: Vec<EditableEntry>, -} - -#[derive(Clone, Debug)] -enum EntryData { - Borrowed(Range<usize>), - Modified(Vec<u8>), -} - -#[derive(Clone, Debug)] -struct EditableEntry { - meta: EntryMeta, - name_raw: [u8; 36], - data: EntryData, -} - -impl EditableEntry { - fn data_slice<'a>(&'a self, source: &'a Arc<[u8]>) -> &'a [u8] { - match &self.data { - EntryData::Borrowed(range) => &source[range.clone()], - EntryData::Modified(vec) => vec.as_slice(), - } - } -} - -#[derive(Clone, Debug)] -pub struct NewEntry<'a> { - pub kind: u32, - pub attr1: u32, - pub attr2: u32, - pub attr3: u32, - pub name: &'a str, - pub data: &'a [u8], -} - -impl Editor { - pub fn entries(&self) -> impl Iterator<Item = EntryRef<'_>> { - self.entries - .iter() - .enumerate() - .map(|(idx, entry)| EntryRef { - id: EntryId(u32::try_from(idx).expect("entry count validated at add")), - meta: &entry.meta, - }) - } - - pub fn add(&mut self, entry: NewEntry<'_>) -> Result<EntryId> { - let name_raw = encode_name_field(entry.name)?; - let id_u32 = u32::try_from(self.entries.len()).map_err(|_| Error::IntegerOverflow)?; - let data_size = u32::try_from(entry.data.len()).map_err(|_| Error::IntegerOverflow)?; - self.entries.push(EditableEntry { - meta: EntryMeta { - kind: entry.kind, - attr1: entry.attr1, - attr2: entry.attr2, - attr3: entry.attr3, - name: decode_name(entry_name_bytes(&name_raw)), - data_offset: 0, - data_size, - sort_index: 0, - }, - name_raw, - data: EntryData::Modified(entry.data.to_vec()), - }); - Ok(EntryId(id_u32)) - } - - pub fn replace_data(&mut self, id: EntryId, data: &[u8]) -> Result<()> { - let idx = usize::try_from(id.0).map_err(|_| Error::IntegerOverflow)?; - let Some(entry) = self.entries.get_mut(idx) else { - return Err(Error::EntryIdOutOfRange { - id: id.0, - entry_count: self.entries.len().try_into().unwrap_or(u32::MAX), - }); - }; - entry.meta.data_size = u32::try_from(data.len()).map_err(|_| Error::IntegerOverflow)?; - // Replace with new data (triggers copy-on-write if borrowed) - entry.data = EntryData::Modified(data.to_vec()); - Ok(()) - } - - pub fn remove(&mut self, id: EntryId) -> Result<()> { - let idx = usize::try_from(id.0).map_err(|_| Error::IntegerOverflow)?; - if idx >= self.entries.len() { - return Err(Error::EntryIdOutOfRange { - id: id.0, - entry_count: self.entries.len().try_into().unwrap_or(u32::MAX), - }); - } - self.entries.remove(idx); - Ok(()) - } - - pub fn commit(mut self) -> Result<()> { - let count_u32 = u32::try_from(self.entries.len()).map_err(|_| Error::IntegerOverflow)?; - - // Pre-calculate capacity to avoid reallocations - let total_data_size: usize = self - .entries - .iter() - .map(|e| e.data_slice(&self.source).len()) - .sum(); - let padding_estimate = self.entries.len() * 8; // Max 8 bytes padding per entry - let directory_size = self.entries.len() * 64; // 64 bytes per entry - let capacity = 16 + total_data_size + padding_estimate + directory_size; - - let mut out = Vec::with_capacity(capacity); - out.resize(16, 0); // Header - - // Keep reference to source for copy-on-write - let source = &self.source; - - for entry in &mut self.entries { - entry.meta.data_offset = - u64::try_from(out.len()).map_err(|_| Error::IntegerOverflow)?; - - // Calculate size and get slice separately to avoid borrow conflicts - let data_len = entry.data_slice(source).len(); - entry.meta.data_size = u32::try_from(data_len).map_err(|_| Error::IntegerOverflow)?; - - // Now get the slice again for writing - let data_slice = entry.data_slice(source); - out.extend_from_slice(data_slice); - - let padding = (8 - (out.len() % 8)) % 8; - if padding > 0 { - out.resize(out.len() + padding, 0); - } - } - - let mut sort_order: Vec<usize> = (0..self.entries.len()).collect(); - sort_order.sort_by(|a, b| { - cmp_name_case_insensitive( - entry_name_bytes(&self.entries[*a].name_raw), - entry_name_bytes(&self.entries[*b].name_raw), - ) - }); - - for (idx, entry) in self.entries.iter_mut().enumerate() { - entry.meta.sort_index = - u32::try_from(sort_order[idx]).map_err(|_| Error::IntegerOverflow)?; - } - - for entry in &self.entries { - let data_offset_u32 = - u32::try_from(entry.meta.data_offset).map_err(|_| Error::IntegerOverflow)?; - push_u32(&mut out, entry.meta.kind); - push_u32(&mut out, entry.meta.attr1); - push_u32(&mut out, entry.meta.attr2); - push_u32(&mut out, entry.meta.data_size); - push_u32(&mut out, entry.meta.attr3); - out.extend_from_slice(&entry.name_raw); - push_u32(&mut out, data_offset_u32); - push_u32(&mut out, entry.meta.sort_index); - } - - let total_size_u32 = u32::try_from(out.len()).map_err(|_| Error::IntegerOverflow)?; - out[0..4].copy_from_slice(b"NRes"); - out[4..8].copy_from_slice(&0x100_u32.to_le_bytes()); - out[8..12].copy_from_slice(&count_u32.to_le_bytes()); - out[12..16].copy_from_slice(&total_size_u32.to_le_bytes()); - - write_atomic(&self.path, &out) - } -} - -fn parse_archive(bytes: &[u8], raw_mode: bool) -> Result<(Vec<EntryRecord>, u64)> { - if raw_mode { - let data_size = u32::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?; - let entry = EntryRecord { - meta: EntryMeta { - kind: 0, - attr1: 0, - attr2: 0, - attr3: 0, - name: String::from("RAW"), - data_offset: 0, - data_size, - sort_index: 0, - }, - name_raw: { - let mut name = [0u8; 36]; - let bytes_name = b"RAW"; - name[..bytes_name.len()].copy_from_slice(bytes_name); - name - }, - }; - return Ok(( - vec![entry], - u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?, - )); - } - - if bytes.len() < 16 { - let mut got = [0u8; 4]; - let copy_len = bytes.len().min(4); - got[..copy_len].copy_from_slice(&bytes[..copy_len]); - return Err(Error::InvalidMagic { got }); - } - - let mut magic = [0u8; 4]; - magic.copy_from_slice(&bytes[0..4]); - if &magic != b"NRes" { - return Err(Error::InvalidMagic { got: magic }); - } - - let version = read_u32(bytes, 4)?; - if version != 0x100 { - return Err(Error::UnsupportedVersion { got: version }); - } - - let entry_count_i32 = i32::from_le_bytes( - bytes[8..12] - .try_into() - .map_err(|_| Error::IntegerOverflow)?, - ); - if entry_count_i32 < 0 { - return Err(Error::InvalidEntryCount { - got: entry_count_i32, - }); - } - let entry_count = usize::try_from(entry_count_i32).map_err(|_| Error::IntegerOverflow)?; - - // Validate entry_count fits in u32 (required for EntryId) - if entry_count > u32::MAX as usize { - return Err(Error::TooManyEntries { got: entry_count }); - } - - let total_size = read_u32(bytes, 12)?; - let actual_size = u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?; - if u64::from(total_size) != actual_size { - return Err(Error::TotalSizeMismatch { - header: total_size, - actual: actual_size, - }); - } - - let directory_len = u64::try_from(entry_count) - .map_err(|_| Error::IntegerOverflow)? - .checked_mul(64) - .ok_or(Error::IntegerOverflow)?; - let directory_offset = - u64::from(total_size) - .checked_sub(directory_len) - .ok_or(Error::DirectoryOutOfBounds { - directory_offset: 0, - directory_len, - file_len: actual_size, - })?; - - if directory_offset < 16 || directory_offset + directory_len > actual_size { - return Err(Error::DirectoryOutOfBounds { - directory_offset, - directory_len, - file_len: actual_size, - }); - } - - let mut entries = Vec::with_capacity(entry_count); - for index in 0..entry_count { - let base = usize::try_from(directory_offset) - .map_err(|_| Error::IntegerOverflow)? - .checked_add(index.checked_mul(64).ok_or(Error::IntegerOverflow)?) - .ok_or(Error::IntegerOverflow)?; - - let kind = read_u32(bytes, base)?; - let attr1 = read_u32(bytes, base + 4)?; - let attr2 = read_u32(bytes, base + 8)?; - let data_size = read_u32(bytes, base + 12)?; - let attr3 = read_u32(bytes, base + 16)?; - - let mut name_raw = [0u8; 36]; - let name_slice = bytes - .get(base + 20..base + 56) - .ok_or(Error::IntegerOverflow)?; - name_raw.copy_from_slice(name_slice); - - let name_bytes = entry_name_bytes(&name_raw); - if name_bytes.len() > 35 { - return Err(Error::NameTooLong { - got: name_bytes.len(), - max: 35, - }); - } - - let data_offset = u64::from(read_u32(bytes, base + 56)?); - let sort_index = read_u32(bytes, base + 60)?; - - let end = data_offset - .checked_add(u64::from(data_size)) - .ok_or(Error::IntegerOverflow)?; - if data_offset < 16 || end > directory_offset { - return Err(Error::EntryDataOutOfBounds { - id: u32::try_from(index).map_err(|_| Error::IntegerOverflow)?, - offset: data_offset, - size: data_size, - directory_offset, - }); - } - - entries.push(EntryRecord { - meta: EntryMeta { - kind, - attr1, - attr2, - attr3, - name: decode_name(name_bytes), - data_offset, - data_size, - sort_index, - }, - name_raw, - }); - } - - Ok((entries, directory_offset)) -} - -fn checked_range(offset: u64, size: u32, bytes_len: usize) -> Result<Range<usize>> { - let start = usize::try_from(offset).map_err(|_| Error::IntegerOverflow)?; - let len = usize::try_from(size).map_err(|_| Error::IntegerOverflow)?; - let end = start.checked_add(len).ok_or(Error::IntegerOverflow)?; - if end > bytes_len { - return Err(Error::IntegerOverflow); - } - Ok(start..end) -} - -fn read_u32(bytes: &[u8], offset: usize) -> Result<u32> { - let data = bytes - .get(offset..offset + 4) - .ok_or(Error::IntegerOverflow)?; - let arr: [u8; 4] = data.try_into().map_err(|_| Error::IntegerOverflow)?; - Ok(u32::from_le_bytes(arr)) -} - -fn push_u32(out: &mut Vec<u8>, value: u32) { - out.extend_from_slice(&value.to_le_bytes()); -} - -fn encode_name_field(name: &str) -> Result<[u8; 36]> { - let bytes = name.as_bytes(); - if bytes.contains(&0) { - return Err(Error::NameContainsNul); - } - if bytes.len() > 35 { - return Err(Error::NameTooLong { - got: bytes.len(), - max: 35, - }); - } - - let mut out = [0u8; 36]; - out[..bytes.len()].copy_from_slice(bytes); - Ok(out) -} - -fn entry_name_bytes(raw: &[u8; 36]) -> &[u8] { - let len = raw.iter().position(|&b| b == 0).unwrap_or(raw.len()); - &raw[..len] -} - -fn decode_name(name: &[u8]) -> String { - name.iter().map(|b| char::from(*b)).collect() -} - -fn cmp_name_case_insensitive(a: &[u8], b: &[u8]) -> Ordering { - let mut idx = 0usize; - let min_len = a.len().min(b.len()); - while idx < min_len { - let left = ascii_lower(a[idx]); - let right = ascii_lower(b[idx]); - if left != right { - return left.cmp(&right); - } - idx += 1; - } - a.len().cmp(&b.len()) -} - -fn ascii_lower(value: u8) -> u8 { - if value.is_ascii_uppercase() { - value + 32 - } else { - value - } -} - -fn prefetch_pages(bytes: &[u8]) { - use std::sync::atomic::{compiler_fence, Ordering}; - - let mut cursor = 0usize; - let mut sink = 0u8; - while cursor < bytes.len() { - sink ^= bytes[cursor]; - cursor = cursor.saturating_add(4096); - } - compiler_fence(Ordering::SeqCst); - let _ = sink; -} - -fn write_atomic(path: &Path, content: &[u8]) -> Result<()> { - let file_name = path - .file_name() - .and_then(|name| name.to_str()) - .unwrap_or("archive"); - let parent = path.parent().unwrap_or_else(|| Path::new(".")); - - let mut temp_path = None; - for attempt in 0..128u32 { - let name = format!( - ".{}.tmp.{}.{}.{}", - file_name, - std::process::id(), - unix_time_nanos(), - attempt - ); - let candidate = parent.join(name); - let opened = FsOpenOptions::new() - .create_new(true) - .write(true) - .open(&candidate); - if let Ok(mut file) = opened { - file.write_all(content)?; - file.sync_all()?; - temp_path = Some((candidate, file)); - break; - } - } - - let Some((tmp_path, mut file)) = temp_path else { - return Err(Error::Io(std::io::Error::new( - std::io::ErrorKind::AlreadyExists, - "failed to create temporary file for atomic write", - ))); - }; - - file.flush()?; - drop(file); - - if let Err(err) = replace_file_atomically(&tmp_path, path) { - let _ = fs::remove_file(&tmp_path); - return Err(Error::Io(err)); - } - - Ok(()) -} - -#[cfg(not(windows))] -fn replace_file_atomically(src: &Path, dst: &Path) -> std::io::Result<()> { - fs::rename(src, dst) -} - -#[cfg(windows)] -fn replace_file_atomically(src: &Path, dst: &Path) -> std::io::Result<()> { - use std::iter; - use std::os::windows::ffi::OsStrExt; - use windows_sys::Win32::Storage::FileSystem::{ - MoveFileExW, MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH, - }; - - let src_wide: Vec<u16> = src.as_os_str().encode_wide().chain(iter::once(0)).collect(); - let dst_wide: Vec<u16> = dst.as_os_str().encode_wide().chain(iter::once(0)).collect(); - - // Replace destination in one OS call, avoiding remove+rename gaps on Windows. - let ok = unsafe { - MoveFileExW( - src_wide.as_ptr(), - dst_wide.as_ptr(), - MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH, - ) - }; - - if ok == 0 { - Err(std::io::Error::last_os_error()) - } else { - Ok(()) - } -} - -fn unix_time_nanos() -> u128 { - match SystemTime::now().duration_since(UNIX_EPOCH) { - Ok(duration) => duration.as_nanos(), - Err(_) => 0, - } -} - -#[cfg(test)] -mod tests; diff --git a/crates/nres/src/tests.rs b/crates/nres/src/tests.rs deleted file mode 100644 index 6de02e5..0000000 --- a/crates/nres/src/tests.rs +++ /dev/null @@ -1,996 +0,0 @@ -use super::*; -use std::any::Any; -use std::fs; -use std::panic::{catch_unwind, AssertUnwindSafe}; - -#[derive(Clone)] -struct SyntheticEntry<'a> { - kind: u32, - attr1: u32, - attr2: u32, - attr3: u32, - name: &'a str, - data: &'a [u8], -} - -fn collect_files_recursive(root: &Path, out: &mut Vec<PathBuf>) { - let Ok(entries) = fs::read_dir(root) else { - return; - }; - for entry in entries.flatten() { - let path = entry.path(); - if path.is_dir() { - collect_files_recursive(&path, out); - } else if path.is_file() { - out.push(path); - } - } -} - -fn nres_test_files() -> Vec<PathBuf> { - let root = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("..") - .join("..") - .join("testdata") - .join("nres"); - let mut files = Vec::new(); - collect_files_recursive(&root, &mut files); - files.sort(); - files - .into_iter() - .filter(|path| { - fs::read(path) - .map(|data| data.get(0..4) == Some(b"NRes")) - .unwrap_or(false) - }) - .collect() -} - -fn make_temp_copy(original: &Path, bytes: &[u8]) -> PathBuf { - let mut path = std::env::temp_dir(); - let file_name = original - .file_name() - .and_then(|v| v.to_str()) - .unwrap_or("archive"); - path.push(format!( - "nres-test-{}-{}-{}", - std::process::id(), - unix_time_nanos(), - file_name - )); - fs::write(&path, bytes).expect("failed to create temp file"); - path -} - -fn panic_message(payload: Box<dyn Any + Send>) -> String { - let any = payload.as_ref(); - if let Some(message) = any.downcast_ref::<String>() { - return message.clone(); - } - if let Some(message) = any.downcast_ref::<&str>() { - return (*message).to_string(); - } - String::from("panic without message") -} - -fn read_u32_le(bytes: &[u8], offset: usize) -> u32 { - let slice = bytes - .get(offset..offset + 4) - .expect("u32 read out of bounds in test"); - let arr: [u8; 4] = slice.try_into().expect("u32 conversion failed in test"); - u32::from_le_bytes(arr) -} - -fn read_i32_le(bytes: &[u8], offset: usize) -> i32 { - let slice = bytes - .get(offset..offset + 4) - .expect("i32 read out of bounds in test"); - let arr: [u8; 4] = slice.try_into().expect("i32 conversion failed in test"); - i32::from_le_bytes(arr) -} - -fn name_field_bytes(raw: &[u8; 36]) -> Option<&[u8]> { - let nul = raw.iter().position(|value| *value == 0)?; - Some(&raw[..nul]) -} - -fn build_nres_bytes(entries: &[SyntheticEntry<'_>]) -> Vec<u8> { - let mut out = vec![0u8; 16]; - let mut offsets = Vec::with_capacity(entries.len()); - - for entry in entries { - offsets.push(u32::try_from(out.len()).expect("offset overflow")); - out.extend_from_slice(entry.data); - let padding = (8 - (out.len() % 8)) % 8; - if padding > 0 { - out.resize(out.len() + padding, 0); - } - } - - let mut sort_order: Vec<usize> = (0..entries.len()).collect(); - sort_order.sort_by(|a, b| { - cmp_name_case_insensitive(entries[*a].name.as_bytes(), entries[*b].name.as_bytes()) - }); - - for (index, entry) in entries.iter().enumerate() { - let mut name_raw = [0u8; 36]; - let name_bytes = entry.name.as_bytes(); - assert!(name_bytes.len() <= 35, "name too long in fixture"); - name_raw[..name_bytes.len()].copy_from_slice(name_bytes); - - push_u32(&mut out, entry.kind); - push_u32(&mut out, entry.attr1); - push_u32(&mut out, entry.attr2); - push_u32( - &mut out, - u32::try_from(entry.data.len()).expect("data size overflow"), - ); - push_u32(&mut out, entry.attr3); - out.extend_from_slice(&name_raw); - push_u32(&mut out, offsets[index]); - push_u32( - &mut out, - u32::try_from(sort_order[index]).expect("sort index overflow"), - ); - } - - out[0..4].copy_from_slice(b"NRes"); - out[4..8].copy_from_slice(&0x100_u32.to_le_bytes()); - out[8..12].copy_from_slice( - &u32::try_from(entries.len()) - .expect("count overflow") - .to_le_bytes(), - ); - let total_size = u32::try_from(out.len()).expect("size overflow"); - out[12..16].copy_from_slice(&total_size.to_le_bytes()); - out -} - -#[test] -fn nres_docs_structural_invariants_all_files() { - let files = nres_test_files(); - if files.is_empty() { - eprintln!( - "skipping nres_docs_structural_invariants_all_files: no NRes archives in testdata/nres" - ); - return; - } - - for path in files { - let bytes = fs::read(&path).unwrap_or_else(|err| { - panic!("failed to read {}: {err}", path.display()); - }); - - assert!( - bytes.len() >= 16, - "NRes header too short in {}", - path.display() - ); - assert_eq!(&bytes[0..4], b"NRes", "bad magic in {}", path.display()); - assert_eq!( - read_u32_le(&bytes, 4), - 0x100, - "bad version in {}", - path.display() - ); - assert_eq!( - usize::try_from(read_u32_le(&bytes, 12)).expect("size overflow"), - bytes.len(), - "header.total_size mismatch in {}", - path.display() - ); - - let entry_count_i32 = read_i32_le(&bytes, 8); - assert!( - entry_count_i32 >= 0, - "negative entry_count={} in {}", - entry_count_i32, - path.display() - ); - let entry_count = usize::try_from(entry_count_i32).expect("entry_count overflow"); - let directory_len = entry_count.checked_mul(64).expect("directory_len overflow"); - let directory_offset = bytes - .len() - .checked_sub(directory_len) - .unwrap_or_else(|| panic!("directory underflow in {}", path.display())); - assert!( - directory_offset >= 16, - "directory offset before data area in {}", - path.display() - ); - assert_eq!( - directory_offset + directory_len, - bytes.len(), - "directory not at file end in {}", - path.display() - ); - - let mut sort_indices = Vec::with_capacity(entry_count); - let mut entries = Vec::with_capacity(entry_count); - for index in 0..entry_count { - let base = directory_offset + index * 64; - let size = usize::try_from(read_u32_le(&bytes, base + 12)).expect("size overflow"); - let data_offset = - usize::try_from(read_u32_le(&bytes, base + 56)).expect("offset overflow"); - let sort_index = - usize::try_from(read_u32_le(&bytes, base + 60)).expect("sort_index overflow"); - - let mut name_raw = [0u8; 36]; - name_raw.copy_from_slice( - bytes - .get(base + 20..base + 56) - .expect("name field out of bounds in test"), - ); - let name_bytes = name_field_bytes(&name_raw).unwrap_or_else(|| { - panic!( - "name field without NUL terminator in {} entry #{index}", - path.display() - ) - }); - assert!( - name_bytes.len() <= 35, - "name longer than 35 bytes in {} entry #{index}", - path.display() - ); - - sort_indices.push(sort_index); - entries.push((name_bytes.to_vec(), data_offset, size)); - } - - let mut expected_sort: Vec<usize> = (0..entry_count).collect(); - expected_sort.sort_by(|a, b| cmp_name_case_insensitive(&entries[*a].0, &entries[*b].0)); - assert_eq!( - sort_indices, - expected_sort, - "sort_index table mismatch in {}", - path.display() - ); - - let mut data_regions: Vec<(usize, usize)> = - entries.iter().map(|(_, off, size)| (*off, *size)).collect(); - data_regions.sort_by_key(|(off, _)| *off); - - for (idx, (data_offset, size)) in data_regions.iter().enumerate() { - assert_eq!( - data_offset % 8, - 0, - "data offset is not 8-byte aligned in {} (region #{idx})", - path.display() - ); - assert!( - *data_offset >= 16, - "data offset before header end in {} (region #{idx})", - path.display() - ); - assert!( - data_offset.checked_add(*size).unwrap_or(usize::MAX) <= directory_offset, - "data region overlaps directory in {} (region #{idx})", - path.display() - ); - } - - for pair in data_regions.windows(2) { - let (start, size) = pair[0]; - let (next_start, _) = pair[1]; - let end = start - .checked_add(size) - .unwrap_or_else(|| panic!("size overflow in {}", path.display())); - assert!( - end <= next_start, - "overlapping data regions in {}: [{start}, {end}) and next at {next_start}", - path.display() - ); - - for (offset, value) in bytes[end..next_start].iter().enumerate() { - assert_eq!( - *value, - 0, - "non-zero alignment padding in {} at offset {}", - path.display(), - end + offset - ); - } - } - } -} - -#[test] -fn nres_read_and_roundtrip_all_files() { - let files = nres_test_files(); - if files.is_empty() { - eprintln!("skipping nres_read_and_roundtrip_all_files: no NRes archives in testdata/nres"); - return; - } - - let checked = files.len(); - let mut success = 0usize; - let mut failures = Vec::new(); - - for path in files { - let display_path = path.display().to_string(); - let result = catch_unwind(AssertUnwindSafe(|| { - let original = fs::read(&path).expect("failed to read archive"); - let archive = Archive::open_path(&path) - .unwrap_or_else(|err| panic!("failed to open {}: {err}", path.display())); - - let count = archive.entry_count(); - assert_eq!( - count, - archive.entries().count(), - "entry count mismatch: {}", - path.display() - ); - - for idx in 0..count { - let id = EntryId(idx as u32); - let entry = archive - .get(id) - .unwrap_or_else(|| panic!("missing entry #{idx} in {}", path.display())); - - let payload = archive.read(id).unwrap_or_else(|err| { - panic!("read failed for {} entry #{idx}: {err}", path.display()) - }); - - let mut out = Vec::new(); - let written = archive.read_into(id, &mut out).unwrap_or_else(|err| { - panic!( - "read_into failed for {} entry #{idx}: {err}", - path.display() - ) - }); - assert_eq!( - written, - payload.as_slice().len(), - "size mismatch in {} entry #{idx}", - path.display() - ); - assert_eq!( - out.as_slice(), - payload.as_slice(), - "payload mismatch in {} entry #{idx}", - path.display() - ); - - let raw = archive - .raw_slice(id) - .unwrap_or_else(|err| { - panic!( - "raw_slice failed for {} entry #{idx}: {err}", - path.display() - ) - }) - .expect("raw_slice must return Some for file-backed archive"); - assert_eq!( - raw, - payload.as_slice(), - "raw slice mismatch in {} entry #{idx}", - path.display() - ); - - let found = archive.find(&entry.meta.name).unwrap_or_else(|| { - panic!( - "find failed for name '{}' in {}", - entry.meta.name, - path.display() - ) - }); - let found_meta = archive.get(found).expect("find returned invalid id"); - assert!( - found_meta.meta.name.eq_ignore_ascii_case(&entry.meta.name), - "find returned unrelated entry in {}", - path.display() - ); - } - - let temp_copy = make_temp_copy(&path, &original); - let mut editor = Archive::edit_path(&temp_copy) - .unwrap_or_else(|err| panic!("edit_path failed for {}: {err}", path.display())); - - for idx in 0..count { - let data = archive - .read(EntryId(idx as u32)) - .unwrap_or_else(|err| { - panic!( - "read before replace failed for {} entry #{idx}: {err}", - path.display() - ) - }) - .into_owned(); - editor - .replace_data(EntryId(idx as u32), &data) - .unwrap_or_else(|err| { - panic!( - "replace_data failed for {} entry #{idx}: {err}", - path.display() - ) - }); - } - - editor - .commit() - .unwrap_or_else(|err| panic!("commit failed for {}: {err}", path.display())); - let rebuilt = fs::read(&temp_copy).expect("failed to read rebuilt archive"); - let _ = fs::remove_file(&temp_copy); - - assert_eq!( - original, - rebuilt, - "byte-to-byte roundtrip mismatch for {}", - path.display() - ); - })); - - match result { - Ok(()) => success += 1, - Err(payload) => { - failures.push(format!("{}: {}", display_path, panic_message(payload))); - } - } - } - - let failed = failures.len(); - eprintln!( - "NRes summary: checked={}, success={}, failed={}", - checked, success, failed - ); - if !failures.is_empty() { - panic!( - "NRes validation failed.\nsummary: checked={}, success={}, failed={}\n{}", - checked, - success, - failed, - failures.join("\n") - ); - } -} - -#[test] -fn nres_raw_mode_exposes_whole_file() { - let files = nres_test_files(); - let Some(first) = files.first() else { - eprintln!("skipping nres_raw_mode_exposes_whole_file: no NRes archives in testdata/nres"); - return; - }; - let original = fs::read(first).expect("failed to read archive"); - let arc: Arc<[u8]> = Arc::from(original.clone().into_boxed_slice()); - - let archive = Archive::open_bytes( - arc, - OpenOptions { - raw_mode: true, - sequential_hint: false, - prefetch_pages: false, - }, - ) - .expect("raw mode open failed"); - - assert_eq!(archive.entry_count(), 1); - let data = archive.read(EntryId(0)).expect("raw read failed"); - assert_eq!(data.as_slice(), original.as_slice()); -} - -#[test] -fn nres_raw_mode_accepts_non_nres_bytes() { - let payload = b"not-an-nres-archive".to_vec(); - let bytes: Arc<[u8]> = Arc::from(payload.clone().into_boxed_slice()); - - match Archive::open_bytes(bytes.clone(), OpenOptions::default()) { - Err(Error::InvalidMagic { .. }) => {} - other => panic!("expected InvalidMagic without raw_mode, got {other:?}"), - } - - let archive = Archive::open_bytes( - bytes, - OpenOptions { - raw_mode: true, - sequential_hint: false, - prefetch_pages: false, - }, - ) - .expect("raw_mode should accept any bytes"); - - assert_eq!(archive.entry_count(), 1); - assert_eq!(archive.find("raw"), Some(EntryId(0))); - assert_eq!( - archive - .read(EntryId(0)) - .expect("raw read failed") - .as_slice(), - payload.as_slice() - ); -} - -#[test] -fn nres_open_options_hints_do_not_change_payload() { - let payload: Vec<u8> = (0..70_000u32).map(|v| (v % 251) as u8).collect(); - let src = build_nres_bytes(&[SyntheticEntry { - kind: 7, - attr1: 70, - attr2: 700, - attr3: 7000, - name: "big.bin", - data: &payload, - }]); - let arc: Arc<[u8]> = Arc::from(src.into_boxed_slice()); - - let baseline = Archive::open_bytes(arc.clone(), OpenOptions::default()) - .expect("baseline open should succeed"); - let hinted = Archive::open_bytes( - arc, - OpenOptions { - raw_mode: false, - sequential_hint: true, - prefetch_pages: true, - }, - ) - .expect("open with hints should succeed"); - - assert_eq!(baseline.entry_count(), 1); - assert_eq!(hinted.entry_count(), 1); - assert_eq!(baseline.find("BIG.BIN"), Some(EntryId(0))); - assert_eq!(hinted.find("big.bin"), Some(EntryId(0))); - assert_eq!( - baseline - .read(EntryId(0)) - .expect("baseline read failed") - .as_slice(), - hinted - .read(EntryId(0)) - .expect("hinted read failed") - .as_slice() - ); -} - -#[test] -fn nres_commit_empty_archive_has_minimal_layout() { - let mut path = std::env::temp_dir(); - path.push(format!( - "nres-empty-commit-{}-{}.lib", - std::process::id(), - unix_time_nanos() - )); - fs::write(&path, build_nres_bytes(&[])).expect("write empty archive failed"); - - Archive::edit_path(&path) - .expect("edit_path failed for empty archive") - .commit() - .expect("commit failed for empty archive"); - - let bytes = fs::read(&path).expect("failed to read committed archive"); - assert_eq!(bytes.len(), 16, "empty archive must contain only header"); - assert_eq!(&bytes[0..4], b"NRes"); - assert_eq!(read_u32_le(&bytes, 4), 0x100); - assert_eq!(read_u32_le(&bytes, 8), 0); - assert_eq!(read_u32_le(&bytes, 12), 16); - - let _ = fs::remove_file(&path); -} - -#[test] -fn nres_commit_recomputes_header_directory_and_sort_table() { - let mut path = std::env::temp_dir(); - path.push(format!( - "nres-commit-layout-{}-{}.lib", - std::process::id(), - unix_time_nanos() - )); - fs::write(&path, build_nres_bytes(&[])).expect("write empty archive failed"); - - let mut editor = Archive::edit_path(&path).expect("edit_path failed"); - editor - .add(NewEntry { - kind: 10, - attr1: 1, - attr2: 2, - attr3: 3, - name: "Zulu", - data: b"aaaaa", - }) - .expect("add #0 failed"); - editor - .add(NewEntry { - kind: 11, - attr1: 4, - attr2: 5, - attr3: 6, - name: "alpha", - data: b"bbbbbbbb", - }) - .expect("add #1 failed"); - editor - .add(NewEntry { - kind: 12, - attr1: 7, - attr2: 8, - attr3: 9, - name: "Beta", - data: b"cccc", - }) - .expect("add #2 failed"); - editor.commit().expect("commit failed"); - - let bytes = fs::read(&path).expect("failed to read committed archive"); - assert_eq!(&bytes[0..4], b"NRes"); - assert_eq!(read_u32_le(&bytes, 4), 0x100); - - let entry_count = usize::try_from(read_u32_le(&bytes, 8)).expect("entry_count overflow"); - let total_size = usize::try_from(read_u32_le(&bytes, 12)).expect("total_size overflow"); - assert_eq!(entry_count, 3); - assert_eq!(total_size, bytes.len()); - - let directory_offset = total_size - .checked_sub(entry_count * 64) - .expect("invalid directory offset"); - assert!(directory_offset >= 16); - - let mut sort_indices = Vec::new(); - let mut prev_data_end = 16usize; - for idx in 0..entry_count { - let base = directory_offset + idx * 64; - let data_size = usize::try_from(read_u32_le(&bytes, base + 12)).expect("size overflow"); - let data_offset = usize::try_from(read_u32_le(&bytes, base + 56)).expect("offset overflow"); - let sort_index = - usize::try_from(read_u32_le(&bytes, base + 60)).expect("sort index overflow"); - - assert_eq!( - data_offset % 8, - 0, - "entry #{idx} data offset must be 8-byte aligned" - ); - assert!( - data_offset >= prev_data_end, - "entry #{idx} offset regressed" - ); - assert!( - data_offset + data_size <= directory_offset, - "entry #{idx} overlaps directory" - ); - prev_data_end = data_offset + data_size; - sort_indices.push(sort_index); - } - - let names = ["Zulu", "alpha", "Beta"]; - let mut expected_sort: Vec<usize> = (0..names.len()).collect(); - expected_sort - .sort_by(|a, b| cmp_name_case_insensitive(names[*a].as_bytes(), names[*b].as_bytes())); - assert_eq!( - sort_indices, expected_sort, - "sort table must contain original indexes in case-insensitive alphabetical order" - ); - - let archive = Archive::open_path(&path).expect("re-open failed"); - assert_eq!(archive.find("zulu"), Some(EntryId(0))); - assert_eq!(archive.find("ALPHA"), Some(EntryId(1))); - assert_eq!(archive.find("beta"), Some(EntryId(2))); - - let _ = fs::remove_file(&path); -} - -#[test] -fn nres_synthetic_read_find_and_edit() { - let payload_a = b"alpha"; - let payload_b = b"B"; - let payload_c = b""; - let src = build_nres_bytes(&[ - SyntheticEntry { - kind: 1, - attr1: 10, - attr2: 20, - attr3: 30, - name: "Alpha.TXT", - data: payload_a, - }, - SyntheticEntry { - kind: 2, - attr1: 11, - attr2: 21, - attr3: 31, - name: "beta.bin", - data: payload_b, - }, - SyntheticEntry { - kind: 3, - attr1: 12, - attr2: 22, - attr3: 32, - name: "Gamma", - data: payload_c, - }, - ]); - - let archive = Archive::open_bytes( - Arc::from(src.clone().into_boxed_slice()), - OpenOptions::default(), - ) - .expect("open synthetic nres failed"); - - assert_eq!(archive.entry_count(), 3); - assert_eq!(archive.find("alpha.txt"), Some(EntryId(0))); - assert_eq!(archive.find("BETA.BIN"), Some(EntryId(1))); - assert_eq!(archive.find("gAmMa"), Some(EntryId(2))); - assert_eq!(archive.find("missing"), None); - - assert_eq!( - archive.read(EntryId(0)).expect("read #0 failed").as_slice(), - payload_a - ); - assert_eq!( - archive.read(EntryId(1)).expect("read #1 failed").as_slice(), - payload_b - ); - assert_eq!( - archive.read(EntryId(2)).expect("read #2 failed").as_slice(), - payload_c - ); - - let mut path = std::env::temp_dir(); - path.push(format!( - "nres-synth-edit-{}-{}.lib", - std::process::id(), - unix_time_nanos() - )); - fs::write(&path, &src).expect("write temp synthetic archive failed"); - - let mut editor = Archive::edit_path(&path).expect("edit_path on synthetic archive failed"); - editor - .replace_data(EntryId(1), b"replaced") - .expect("replace_data failed"); - let added = editor - .add(NewEntry { - kind: 4, - attr1: 13, - attr2: 23, - attr3: 33, - name: "delta", - data: b"new payload", - }) - .expect("add failed"); - assert_eq!(added, EntryId(3)); - editor.remove(EntryId(2)).expect("remove failed"); - editor.commit().expect("commit failed"); - - let edited = Archive::open_path(&path).expect("re-open edited archive failed"); - assert_eq!(edited.entry_count(), 3); - assert_eq!( - edited - .read(edited.find("beta.bin").expect("find beta.bin failed")) - .expect("read beta.bin failed") - .as_slice(), - b"replaced" - ); - assert_eq!( - edited - .read(edited.find("delta").expect("find delta failed")) - .expect("read delta failed") - .as_slice(), - b"new payload" - ); - assert_eq!(edited.find("gamma"), None); - - let _ = fs::remove_file(&path); -} - -#[test] -fn nres_max_name_length_roundtrip() { - let max_name = "12345678901234567890123456789012345"; - assert_eq!(max_name.len(), 35); - - let src = build_nres_bytes(&[SyntheticEntry { - kind: 9, - attr1: 1, - attr2: 2, - attr3: 3, - name: max_name, - data: b"payload", - }]); - - let archive = Archive::open_bytes(Arc::from(src.into_boxed_slice()), OpenOptions::default()) - .expect("open synthetic nres failed"); - - assert_eq!(archive.entry_count(), 1); - assert_eq!(archive.find(max_name), Some(EntryId(0))); - assert_eq!( - archive.find(&max_name.to_ascii_lowercase()), - Some(EntryId(0)) - ); - - let entry = archive.get(EntryId(0)).expect("missing entry 0"); - assert_eq!(entry.meta.name, max_name); - assert_eq!( - archive - .read(EntryId(0)) - .expect("read payload failed") - .as_slice(), - b"payload" - ); -} - -#[test] -fn nres_find_falls_back_when_sort_index_is_out_of_range() { - let mut bytes = build_nres_bytes(&[ - SyntheticEntry { - kind: 1, - attr1: 0, - attr2: 0, - attr3: 0, - name: "Alpha", - data: b"a", - }, - SyntheticEntry { - kind: 2, - attr1: 0, - attr2: 0, - attr3: 0, - name: "Beta", - data: b"b", - }, - SyntheticEntry { - kind: 3, - attr1: 0, - attr2: 0, - attr3: 0, - name: "Gamma", - data: b"c", - }, - ]); - - let entry_count = 3usize; - let directory_offset = bytes - .len() - .checked_sub(entry_count * 64) - .expect("directory offset underflow"); - let mid_entry_sort_index = directory_offset + 64 + 60; - bytes[mid_entry_sort_index..mid_entry_sort_index + 4].copy_from_slice(&u32::MAX.to_le_bytes()); - - let archive = Archive::open_bytes(Arc::from(bytes.into_boxed_slice()), OpenOptions::default()) - .expect("open archive with corrupted sort index failed"); - - assert_eq!(archive.find("alpha"), Some(EntryId(0))); - assert_eq!(archive.find("BETA"), Some(EntryId(1))); - assert_eq!(archive.find("gamma"), Some(EntryId(2))); - assert_eq!(archive.find("missing"), None); -} - -#[test] -fn nres_validation_error_cases() { - let valid = build_nres_bytes(&[SyntheticEntry { - kind: 1, - attr1: 2, - attr2: 3, - attr3: 4, - name: "ok", - data: b"1234", - }]); - - let mut invalid_magic = valid.clone(); - invalid_magic[0..4].copy_from_slice(b"FAIL"); - match Archive::open_bytes( - Arc::from(invalid_magic.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::InvalidMagic { .. }) => {} - other => panic!("expected InvalidMagic, got {other:?}"), - } - - let mut invalid_version = valid.clone(); - invalid_version[4..8].copy_from_slice(&0x200_u32.to_le_bytes()); - match Archive::open_bytes( - Arc::from(invalid_version.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::UnsupportedVersion { got }) => assert_eq!(got, 0x200), - other => panic!("expected UnsupportedVersion, got {other:?}"), - } - - let mut bad_total = valid.clone(); - bad_total[12..16].copy_from_slice(&0_u32.to_le_bytes()); - match Archive::open_bytes( - Arc::from(bad_total.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::TotalSizeMismatch { .. }) => {} - other => panic!("expected TotalSizeMismatch, got {other:?}"), - } - - let mut bad_count = valid.clone(); - bad_count[8..12].copy_from_slice(&(-1_i32).to_le_bytes()); - match Archive::open_bytes( - Arc::from(bad_count.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::InvalidEntryCount { got }) => assert_eq!(got, -1), - other => panic!("expected InvalidEntryCount, got {other:?}"), - } - - let mut bad_dir = valid.clone(); - bad_dir[8..12].copy_from_slice(&1000_u32.to_le_bytes()); - match Archive::open_bytes( - Arc::from(bad_dir.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::DirectoryOutOfBounds { .. }) => {} - other => panic!("expected DirectoryOutOfBounds, got {other:?}"), - } - - let mut long_name = valid.clone(); - let entry_base = long_name.len() - 64; - for b in &mut long_name[entry_base + 20..entry_base + 56] { - *b = b'X'; - } - match Archive::open_bytes( - Arc::from(long_name.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::NameTooLong { .. }) => {} - other => panic!("expected NameTooLong, got {other:?}"), - } - - let mut bad_data = valid.clone(); - bad_data[entry_base + 56..entry_base + 60].copy_from_slice(&12_u32.to_le_bytes()); - bad_data[entry_base + 12..entry_base + 16].copy_from_slice(&32_u32.to_le_bytes()); - match Archive::open_bytes( - Arc::from(bad_data.into_boxed_slice()), - OpenOptions::default(), - ) { - Err(Error::EntryDataOutOfBounds { .. }) => {} - other => panic!("expected EntryDataOutOfBounds, got {other:?}"), - } - - let archive = Archive::open_bytes(Arc::from(valid.into_boxed_slice()), OpenOptions::default()) - .expect("open valid archive failed"); - match archive.read(EntryId(99)) { - Err(Error::EntryIdOutOfRange { .. }) => {} - other => panic!("expected EntryIdOutOfRange, got {other:?}"), - } -} - -#[test] -fn nres_editor_validation_error_cases() { - let mut path = std::env::temp_dir(); - path.push(format!( - "nres-editor-errors-{}-{}.lib", - std::process::id(), - unix_time_nanos() - )); - let src = build_nres_bytes(&[]); - fs::write(&path, src).expect("write empty archive failed"); - - let mut editor = Archive::edit_path(&path).expect("edit_path failed"); - - let long_name = "X".repeat(36); - match editor.add(NewEntry { - kind: 0, - attr1: 0, - attr2: 0, - attr3: 0, - name: &long_name, - data: b"", - }) { - Err(Error::NameTooLong { .. }) => {} - other => panic!("expected NameTooLong, got {other:?}"), - } - - match editor.add(NewEntry { - kind: 0, - attr1: 0, - attr2: 0, - attr3: 0, - name: "bad\0name", - data: b"", - }) { - Err(Error::NameContainsNul) => {} - other => panic!("expected NameContainsNul, got {other:?}"), - } - - match editor.replace_data(EntryId(0), b"x") { - Err(Error::EntryIdOutOfRange { .. }) => {} - other => panic!("expected EntryIdOutOfRange, got {other:?}"), - } - - match editor.remove(EntryId(0)) { - Err(Error::EntryIdOutOfRange { .. }) => {} - other => panic!("expected EntryIdOutOfRange, got {other:?}"), - } - - let _ = fs::remove_file(&path); -} diff --git a/crates/rsli/Cargo.toml b/crates/rsli/Cargo.toml deleted file mode 100644 index faad224..0000000 --- a/crates/rsli/Cargo.toml +++ /dev/null @@ -1,8 +0,0 @@ -[package] -name = "rsli" -version = "0.1.0" -edition = "2021" - -[dependencies] -common = { path = "../common" } -flate2 = { version = "1", default-features = false, features = ["rust_backend"] } diff --git a/crates/rsli/README.md b/crates/rsli/README.md deleted file mode 100644 index 27816d6..0000000 --- a/crates/rsli/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# rsli - -Rust-библиотека для чтения архивов формата **RsLi**. - -## Что умеет - -- Открытие библиотеки из файла (`open_path`, `open_path_with`). -- Дешифрование таблицы записей (XOR stream cipher). -- Поддержка AO-трейлера и media overlay (`allow_ao_trailer`). -- Поддержка quirk для Deflate `EOF+1` (`allow_deflate_eof_plus_one`). -- Поиск по имени (`find`, c приведением запроса к uppercase). -- Загрузка данных: -- `load`, `load_into`, `load_packed`, `unpack`, `load_fast`. - -## Поддерживаемые методы упаковки - -- `0x000` None -- `0x020` XorOnly -- `0x040` Lzss -- `0x060` XorLzss -- `0x080` LzssHuffman -- `0x0A0` XorLzssHuffman -- `0x100` Deflate - -## Модель ошибок - -Типизированные ошибки без паник в production-коде (`InvalidMagic`, `UnsupportedVersion`, `EntryTableOutOfBounds`, `PackedSizePastEof`, `DeflateEofPlusOneQuirkRejected`, `UnsupportedMethod`, и др.). - -## Покрытие тестами - -### Реальные файлы - -- Рекурсивный прогон по `testdata/rsli/**`. -- Сейчас в наборе: **2 архива**. -- На реальных данных подтверждены и проходят byte-to-byte проверки методы: -- `0x040` (LZSS) -- `0x100` (Deflate) -- Для каждого архива проверяется: -- `load`/`load_into`/`load_packed`/`unpack`/`load_fast`; -- `find`; -- пересборка и сравнение **byte-to-byte**. - -### Синтетические тесты - -Из-за отсутствия реальных файлов для части методов добавлены синтетические архивы и тесты: - -- Методы: -- `0x000`, `0x020`, `0x060`, `0x080`, `0x0A0`. -- Спецкейсы формата: - - AO trailer + overlay; - - Deflate `EOF+1` (оба режима: accepted/rejected); -- некорректные заголовки/таблицы/смещения/методы. - -## Быстрый запуск тестов - -```bash -cargo test -p rsli -- --nocapture -``` diff --git a/crates/rsli/src/compress/deflate.rs b/crates/rsli/src/compress/deflate.rs deleted file mode 100644 index 6b8ea73..0000000 --- a/crates/rsli/src/compress/deflate.rs +++ /dev/null @@ -1,14 +0,0 @@ -use crate::error::Error; -use crate::Result; -use flate2::read::DeflateDecoder; -use std::io::Read; - -/// Decode raw Deflate (RFC 1951) payload. -pub fn decode_deflate(packed: &[u8]) -> Result<Vec<u8>> { - let mut out = Vec::new(); - let mut decoder = DeflateDecoder::new(packed); - decoder - .read_to_end(&mut out) - .map_err(|_| Error::DecompressionFailed("deflate"))?; - Ok(out) -} diff --git a/crates/rsli/src/compress/lzh.rs b/crates/rsli/src/compress/lzh.rs deleted file mode 100644 index 07dc0c5..0000000 --- a/crates/rsli/src/compress/lzh.rs +++ /dev/null @@ -1,298 +0,0 @@ -use super::xor::XorState; -use crate::error::Error; -use crate::Result; - -pub(crate) const LZH_N: usize = 4096; -pub(crate) const LZH_F: usize = 60; -pub(crate) const LZH_THRESHOLD: usize = 2; -pub(crate) const LZH_N_CHAR: usize = 256 - LZH_THRESHOLD + LZH_F; -pub(crate) const LZH_T: usize = LZH_N_CHAR * 2 - 1; -pub(crate) const LZH_R: usize = LZH_T - 1; -pub(crate) const LZH_MAX_FREQ: u16 = 0x8000; - -/// LZSS-Huffman decompression with optional on-the-fly XOR decryption. -pub fn lzss_huffman_decompress( - data: &[u8], - expected_size: usize, - xor_key: Option<u16>, -) -> Result<Vec<u8>> { - let mut decoder = LzhDecoder::new(data, xor_key); - decoder.decode(expected_size) -} - -struct LzhDecoder<'a> { - bit_reader: BitReader<'a>, - text: [u8; LZH_N], - freq: [u16; LZH_T + 1], - parent: [usize; LZH_T + LZH_N_CHAR], - son: [usize; LZH_T], - d_code: [u8; 256], - d_len: [u8; 256], - ring_pos: usize, -} - -impl<'a> LzhDecoder<'a> { - fn new(data: &'a [u8], xor_key: Option<u16>) -> Self { - let mut decoder = Self { - bit_reader: BitReader::new(data, xor_key), - text: [0x20u8; LZH_N], - freq: [0u16; LZH_T + 1], - parent: [0usize; LZH_T + LZH_N_CHAR], - son: [0usize; LZH_T], - d_code: [0u8; 256], - d_len: [0u8; 256], - ring_pos: LZH_N - LZH_F, - }; - decoder.init_tables(); - decoder.start_huff(); - decoder - } - - fn decode(&mut self, expected_size: usize) -> Result<Vec<u8>> { - let mut out = Vec::with_capacity(expected_size); - - while out.len() < expected_size { - let c = self.decode_char()?; - if c < 256 { - let byte = c as u8; - out.push(byte); - self.text[self.ring_pos] = byte; - self.ring_pos = (self.ring_pos + 1) & (LZH_N - 1); - } else { - let mut offset = self.decode_position()?; - offset = (self.ring_pos.wrapping_sub(offset).wrapping_sub(1)) & (LZH_N - 1); - let mut length = c.saturating_sub(253); - - while length > 0 && out.len() < expected_size { - let byte = self.text[offset]; - out.push(byte); - self.text[self.ring_pos] = byte; - self.ring_pos = (self.ring_pos + 1) & (LZH_N - 1); - offset = (offset + 1) & (LZH_N - 1); - length -= 1; - } - } - } - - if out.len() != expected_size { - return Err(Error::DecompressionFailed("lzss-huffman")); - } - Ok(out) - } - - fn init_tables(&mut self) { - let d_code_group_counts = [1usize, 3, 8, 12, 24, 16]; - let d_len_group_counts = [32usize, 48, 64, 48, 48, 16]; - - let mut group_index = 0u8; - let mut idx = 0usize; - let mut run = 32usize; - for count in d_code_group_counts { - for _ in 0..count { - for _ in 0..run { - self.d_code[idx] = group_index; - idx += 1; - } - group_index = group_index.wrapping_add(1); - } - run >>= 1; - } - - let mut len = 3u8; - idx = 0; - for count in d_len_group_counts { - for _ in 0..count { - self.d_len[idx] = len; - idx += 1; - } - len = len.saturating_add(1); - } - } - - fn start_huff(&mut self) { - for i in 0..LZH_N_CHAR { - self.freq[i] = 1; - self.son[i] = i + LZH_T; - self.parent[i + LZH_T] = i; - } - - let mut i = 0usize; - let mut j = LZH_N_CHAR; - while j <= LZH_R { - self.freq[j] = self.freq[i].saturating_add(self.freq[i + 1]); - self.son[j] = i; - self.parent[i] = j; - self.parent[i + 1] = j; - i += 2; - j += 1; - } - - self.freq[LZH_T] = u16::MAX; - self.parent[LZH_R] = 0; - } - - fn decode_char(&mut self) -> Result<usize> { - let mut node = self.son[LZH_R]; - while node < LZH_T { - let bit = usize::from(self.bit_reader.read_bit()?); - node = self.son[node + bit]; - } - - let c = node - LZH_T; - self.update(c); - Ok(c) - } - - fn decode_position(&mut self) -> Result<usize> { - let i = self.bit_reader.read_bits(8)? as usize; - let mut c = usize::from(self.d_code[i]) << 6; - let mut j = usize::from(self.d_len[i]).saturating_sub(2); - - while j > 0 { - j -= 1; - c |= usize::from(self.bit_reader.read_bit()?) << j; - } - - Ok(c | (i & 0x3F)) - } - - fn update(&mut self, c: usize) { - if self.freq[LZH_R] == LZH_MAX_FREQ { - self.reconstruct(); - } - - let mut current = self.parent[c + LZH_T]; - loop { - self.freq[current] = self.freq[current].saturating_add(1); - let freq = self.freq[current]; - - if current + 1 < self.freq.len() && freq > self.freq[current + 1] { - let mut swap_idx = current + 1; - while swap_idx + 1 < self.freq.len() && freq > self.freq[swap_idx + 1] { - swap_idx += 1; - } - - self.freq.swap(current, swap_idx); - - let left = self.son[current]; - let right = self.son[swap_idx]; - self.son[current] = right; - self.son[swap_idx] = left; - - self.parent[left] = swap_idx; - if left < LZH_T { - self.parent[left + 1] = swap_idx; - } - - self.parent[right] = current; - if right < LZH_T { - self.parent[right + 1] = current; - } - - current = swap_idx; - } - - current = self.parent[current]; - if current == 0 { - break; - } - } - } - - fn reconstruct(&mut self) { - let mut j = 0usize; - for i in 0..LZH_T { - if self.son[i] >= LZH_T { - self.freq[j] = (self.freq[i].saturating_add(1)) / 2; - self.son[j] = self.son[i]; - j += 1; - } - } - - let mut i = 0usize; - let mut current = LZH_N_CHAR; - while current < LZH_T { - let sum = self.freq[i].saturating_add(self.freq[i + 1]); - self.freq[current] = sum; - - let mut insert_at = current; - while insert_at > 0 && sum < self.freq[insert_at - 1] { - insert_at -= 1; - } - - for move_idx in (insert_at..current).rev() { - self.freq[move_idx + 1] = self.freq[move_idx]; - self.son[move_idx + 1] = self.son[move_idx]; - } - - self.freq[insert_at] = sum; - self.son[insert_at] = i; - - i += 2; - current += 1; - } - - for idx in 0..LZH_T { - let node = self.son[idx]; - self.parent[node] = idx; - if node < LZH_T { - self.parent[node + 1] = idx; - } - } - - self.freq[LZH_T] = u16::MAX; - self.parent[LZH_R] = 0; - } -} - -struct BitReader<'a> { - data: &'a [u8], - byte_pos: usize, - bit_mask: u8, - current_byte: u8, - xor_state: Option<XorState>, -} - -impl<'a> BitReader<'a> { - fn new(data: &'a [u8], xor_key: Option<u16>) -> Self { - Self { - data, - byte_pos: 0, - bit_mask: 0x80, - current_byte: 0, - xor_state: xor_key.map(XorState::new), - } - } - - fn read_bit(&mut self) -> Result<u8> { - if self.bit_mask == 0x80 { - let Some(mut byte) = self.data.get(self.byte_pos).copied() else { - return Err(Error::DecompressionFailed("lzss-huffman: unexpected EOF")); - }; - if let Some(state) = &mut self.xor_state { - byte = state.decrypt_byte(byte); - } - self.current_byte = byte; - } - - let bit = if (self.current_byte & self.bit_mask) != 0 { - 1 - } else { - 0 - }; - self.bit_mask >>= 1; - if self.bit_mask == 0 { - self.bit_mask = 0x80; - self.byte_pos = self.byte_pos.saturating_add(1); - } - Ok(bit) - } - - fn read_bits(&mut self, bits: usize) -> Result<u32> { - let mut value = 0u32; - for _ in 0..bits { - value = (value << 1) | u32::from(self.read_bit()?); - } - Ok(value) - } -} diff --git a/crates/rsli/src/compress/lzss.rs b/crates/rsli/src/compress/lzss.rs deleted file mode 100644 index d30345c..0000000 --- a/crates/rsli/src/compress/lzss.rs +++ /dev/null @@ -1,79 +0,0 @@ -use super::xor::XorState; -use crate::error::Error; -use crate::Result; - -/// Simple LZSS decompression with optional on-the-fly XOR decryption -pub fn lzss_decompress_simple( - data: &[u8], - expected_size: usize, - xor_key: Option<u16>, -) -> Result<Vec<u8>> { - let mut ring = [0x20u8; 0x1000]; - let mut ring_pos = 0xFEEusize; - let mut out = Vec::with_capacity(expected_size); - let mut in_pos = 0usize; - - let mut control = 0u8; - let mut bits_left = 0u8; - - // XOR state for on-the-fly decryption - let mut xor_state = xor_key.map(XorState::new); - - // Helper to read byte with optional XOR decryption - let read_byte = |pos: usize, state: &mut Option<XorState>| -> Option<u8> { - let encrypted = data.get(pos).copied()?; - Some(if let Some(ref mut s) = state { - s.decrypt_byte(encrypted) - } else { - encrypted - }) - }; - - while out.len() < expected_size { - if bits_left == 0 { - let byte = read_byte(in_pos, &mut xor_state) - .ok_or(Error::DecompressionFailed("lzss-simple: unexpected EOF"))?; - control = byte; - in_pos += 1; - bits_left = 8; - } - - if (control & 1) != 0 { - let byte = read_byte(in_pos, &mut xor_state) - .ok_or(Error::DecompressionFailed("lzss-simple: unexpected EOF"))?; - in_pos += 1; - - out.push(byte); - ring[ring_pos] = byte; - ring_pos = (ring_pos + 1) & 0x0FFF; - } else { - let low = read_byte(in_pos, &mut xor_state) - .ok_or(Error::DecompressionFailed("lzss-simple: unexpected EOF"))?; - let high = read_byte(in_pos + 1, &mut xor_state) - .ok_or(Error::DecompressionFailed("lzss-simple: unexpected EOF"))?; - in_pos += 2; - - let offset = usize::from(low) | (usize::from(high & 0xF0) << 4); - let length = usize::from((high & 0x0F) + 3); - - for step in 0..length { - let byte = ring[(offset + step) & 0x0FFF]; - out.push(byte); - ring[ring_pos] = byte; - ring_pos = (ring_pos + 1) & 0x0FFF; - if out.len() >= expected_size { - break; - } - } - } - - control >>= 1; - bits_left -= 1; - } - - if out.len() != expected_size { - return Err(Error::DecompressionFailed("lzss-simple")); - } - - Ok(out) -} diff --git a/crates/rsli/src/compress/mod.rs b/crates/rsli/src/compress/mod.rs deleted file mode 100644 index bd23143..0000000 --- a/crates/rsli/src/compress/mod.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod deflate; -pub mod lzh; -pub mod lzss; -pub mod xor; - -pub use deflate::decode_deflate; -pub use lzh::lzss_huffman_decompress; -pub use lzss::lzss_decompress_simple; -pub use xor::{xor_stream, XorState}; diff --git a/crates/rsli/src/compress/xor.rs b/crates/rsli/src/compress/xor.rs deleted file mode 100644 index c4c3d7d..0000000 --- a/crates/rsli/src/compress/xor.rs +++ /dev/null @@ -1,29 +0,0 @@ -/// XOR cipher state for RsLi format -pub struct XorState { - lo: u8, - hi: u8, -} - -impl XorState { - /// Create new XOR state from 16-bit key - pub fn new(key16: u16) -> Self { - Self { - lo: (key16 & 0xFF) as u8, - hi: ((key16 >> 8) & 0xFF) as u8, - } - } - - /// Decrypt a single byte and update state - pub fn decrypt_byte(&mut self, encrypted: u8) -> u8 { - self.lo = self.hi ^ self.lo.wrapping_shl(1); - let decrypted = encrypted ^ self.lo; - self.hi = self.lo ^ (self.hi >> 1); - decrypted - } -} - -/// Decrypt entire buffer with XOR stream cipher -pub fn xor_stream(data: &[u8], key16: u16) -> Vec<u8> { - let mut state = XorState::new(key16); - data.iter().map(|&b| state.decrypt_byte(b)).collect() -} diff --git a/crates/rsli/src/error.rs b/crates/rsli/src/error.rs deleted file mode 100644 index 5a36101..0000000 --- a/crates/rsli/src/error.rs +++ /dev/null @@ -1,140 +0,0 @@ -use core::fmt; - -#[derive(Debug)] -#[non_exhaustive] -pub enum Error { - Io(std::io::Error), - - InvalidMagic { - got: [u8; 2], - }, - UnsupportedVersion { - got: u8, - }, - InvalidEntryCount { - got: i16, - }, - TooManyEntries { - got: usize, - }, - - EntryTableOutOfBounds { - table_offset: u64, - table_len: u64, - file_len: u64, - }, - EntryTableDecryptFailed, - CorruptEntryTable(&'static str), - - EntryIdOutOfRange { - id: u32, - entry_count: u32, - }, - EntryDataOutOfBounds { - id: u32, - offset: u64, - size: u32, - file_len: u64, - }, - - AoTrailerInvalid, - MediaOverlayOutOfBounds { - overlay: u32, - file_len: u64, - }, - - UnsupportedMethod { - raw: u32, - }, - PackedSizePastEof { - id: u32, - offset: u64, - packed_size: u32, - file_len: u64, - }, - DeflateEofPlusOneQuirkRejected { - id: u32, - }, - - DecompressionFailed(&'static str), - OutputSizeMismatch { - expected: u32, - got: u32, - }, - - IntegerOverflow, -} - -impl From<std::io::Error> for Error { - fn from(value: std::io::Error) -> Self { - Self::Io(value) - } -} - -impl fmt::Display for Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - Error::Io(e) => write!(f, "I/O error: {e}"), - Error::InvalidMagic { got } => write!(f, "invalid RsLi magic: {got:02X?}"), - Error::UnsupportedVersion { got } => write!(f, "unsupported RsLi version: {got:#x}"), - Error::InvalidEntryCount { got } => write!(f, "invalid entry_count: {got}"), - Error::TooManyEntries { got } => write!(f, "too many entries: {got} exceeds u32::MAX"), - Error::EntryTableOutOfBounds { - table_offset, - table_len, - file_len, - } => write!( - f, - "entry table out of bounds: off={table_offset}, len={table_len}, file={file_len}" - ), - Error::EntryTableDecryptFailed => write!(f, "failed to decrypt entry table"), - Error::CorruptEntryTable(s) => write!(f, "corrupt entry table: {s}"), - Error::EntryIdOutOfRange { id, entry_count } => { - write!(f, "entry id out of range: id={id}, count={entry_count}") - } - Error::EntryDataOutOfBounds { - id, - offset, - size, - file_len, - } => write!( - f, - "entry data out of bounds: id={id}, off={offset}, size={size}, file={file_len}" - ), - Error::AoTrailerInvalid => write!(f, "invalid AO trailer"), - Error::MediaOverlayOutOfBounds { overlay, file_len } => { - write!( - f, - "media overlay out of bounds: overlay={overlay}, file={file_len}" - ) - } - Error::UnsupportedMethod { raw } => write!(f, "unsupported packing method: {raw:#x}"), - Error::PackedSizePastEof { - id, - offset, - packed_size, - file_len, - } => write!( - f, - "packed range past EOF: id={id}, off={offset}, size={packed_size}, file={file_len}" - ), - Error::DeflateEofPlusOneQuirkRejected { id } => { - write!(f, "deflate EOF+1 quirk rejected for entry {id}") - } - Error::DecompressionFailed(s) => write!(f, "decompression failed: {s}"), - Error::OutputSizeMismatch { expected, got } => { - write!(f, "output size mismatch: expected={expected}, got={got}") - } - Error::IntegerOverflow => write!(f, "integer overflow"), - } - } -} - -impl std::error::Error for Error { - fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { - match self { - Self::Io(err) => Some(err), - _ => None, - } - } -} diff --git a/crates/rsli/src/lib.rs b/crates/rsli/src/lib.rs deleted file mode 100644 index ef29f41..0000000 --- a/crates/rsli/src/lib.rs +++ /dev/null @@ -1,411 +0,0 @@ -pub mod compress; -pub mod error; -pub mod parse; - -use crate::compress::{ - decode_deflate, lzss_decompress_simple, lzss_huffman_decompress, xor_stream, -}; -use crate::error::Error; -use crate::parse::{c_name_bytes, cmp_c_string, parse_library}; -use common::{OutputBuffer, ResourceData}; -use std::cmp::Ordering; -use std::fs; -use std::path::Path; -use std::sync::Arc; - -pub type Result<T> = core::result::Result<T, Error>; - -#[derive(Clone, Debug)] -pub struct OpenOptions { - pub allow_ao_trailer: bool, - pub allow_deflate_eof_plus_one: bool, -} - -impl Default for OpenOptions { - fn default() -> Self { - Self { - allow_ao_trailer: true, - allow_deflate_eof_plus_one: true, - } - } -} - -#[derive(Debug)] -pub struct Library { - bytes: Arc<[u8]>, - entries: Vec<EntryRecord>, - #[cfg(test)] - pub(crate) header_raw: [u8; 32], - #[cfg(test)] - pub(crate) table_plain_original: Vec<u8>, - #[cfg(test)] - pub(crate) xor_seed: u32, - #[cfg(test)] - pub(crate) source_size: usize, - #[cfg(test)] - pub(crate) trailer_raw: Option<[u8; 6]>, -} - -#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -pub struct EntryId(pub u32); - -#[derive(Clone, Debug)] -pub struct EntryMeta { - pub name: String, - pub flags: i32, - pub method: PackMethod, - pub data_offset: u64, - pub packed_size: u32, - pub unpacked_size: u32, -} - -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub enum PackMethod { - None, - XorOnly, - Lzss, - XorLzss, - LzssHuffman, - XorLzssHuffman, - Deflate, - Unknown(u32), -} - -#[derive(Copy, Clone, Debug)] -pub struct EntryRef<'a> { - pub id: EntryId, - pub meta: &'a EntryMeta, -} - -pub struct PackedResource { - pub meta: EntryMeta, - pub packed: Vec<u8>, -} - -#[derive(Clone, Debug)] -pub(crate) struct EntryRecord { - pub(crate) meta: EntryMeta, - pub(crate) name_raw: [u8; 12], - pub(crate) sort_to_original: i16, - pub(crate) key16: u16, - #[cfg(test)] - pub(crate) data_offset_raw: u32, - pub(crate) packed_size_declared: u32, - pub(crate) packed_size_available: usize, - pub(crate) effective_offset: usize, -} - -impl Library { - pub fn open_path(path: impl AsRef<Path>) -> Result<Self> { - Self::open_path_with(path, OpenOptions::default()) - } - - pub fn open_path_with(path: impl AsRef<Path>, opts: OpenOptions) -> Result<Self> { - let bytes = fs::read(path.as_ref())?; - let arc: Arc<[u8]> = Arc::from(bytes.into_boxed_slice()); - parse_library(arc, opts) - } - - pub fn entry_count(&self) -> usize { - self.entries.len() - } - - pub fn entries(&self) -> impl Iterator<Item = EntryRef<'_>> { - self.entries - .iter() - .enumerate() - .map(|(idx, entry)| EntryRef { - id: EntryId(u32::try_from(idx).expect("entry count validated at parse")), - meta: &entry.meta, - }) - } - - pub fn find(&self, name: &str) -> Option<EntryId> { - if self.entries.is_empty() { - return None; - } - - const MAX_INLINE_NAME: usize = 12; - - // Fast path: use stack allocation for short ASCII names (95% of cases) - if name.len() <= MAX_INLINE_NAME && name.is_ascii() { - let mut buf = [0u8; MAX_INLINE_NAME]; - for (i, &b) in name.as_bytes().iter().enumerate() { - buf[i] = b.to_ascii_uppercase(); - } - return self.find_impl(&buf[..name.len()]); - } - - // Slow path: heap allocation for long or non-ASCII names - let query = name.to_ascii_uppercase(); - self.find_impl(query.as_bytes()) - } - - fn find_impl(&self, query_bytes: &[u8]) -> Option<EntryId> { - // Binary search - let mut low = 0usize; - let mut high = self.entries.len(); - while low < high { - let mid = low + (high - low) / 2; - let idx = self.entries[mid].sort_to_original; - if idx < 0 { - break; - } - let idx = usize::try_from(idx).ok()?; - if idx >= self.entries.len() { - break; - } - - let cmp = cmp_c_string(query_bytes, c_name_bytes(&self.entries[idx].name_raw)); - match cmp { - Ordering::Less => high = mid, - Ordering::Greater => low = mid + 1, - Ordering::Equal => { - return Some(EntryId( - u32::try_from(idx).expect("entry count validated at parse"), - )) - } - } - } - - // Linear fallback search - self.entries.iter().enumerate().find_map(|(idx, entry)| { - if cmp_c_string(query_bytes, c_name_bytes(&entry.name_raw)) == Ordering::Equal { - Some(EntryId( - u32::try_from(idx).expect("entry count validated at parse"), - )) - } else { - None - } - }) - } - - pub fn get(&self, id: EntryId) -> Option<EntryRef<'_>> { - let idx = usize::try_from(id.0).ok()?; - let entry = self.entries.get(idx)?; - Some(EntryRef { - id, - meta: &entry.meta, - }) - } - - pub fn load(&self, id: EntryId) -> Result<Vec<u8>> { - let entry = self.entry_by_id(id)?; - let packed = self.packed_slice(id, entry)?; - decode_payload( - packed, - entry.meta.method, - entry.key16, - entry.meta.unpacked_size, - ) - } - - pub fn load_into(&self, id: EntryId, out: &mut dyn OutputBuffer) -> Result<usize> { - let decoded = self.load(id)?; - out.write_exact(&decoded)?; - Ok(decoded.len()) - } - - pub fn load_packed(&self, id: EntryId) -> Result<PackedResource> { - let entry = self.entry_by_id(id)?; - let packed = self.packed_slice(id, entry)?.to_vec(); - Ok(PackedResource { - meta: entry.meta.clone(), - packed, - }) - } - - pub fn unpack(&self, packed: &PackedResource) -> Result<Vec<u8>> { - let key16 = self.resolve_key_for_meta(&packed.meta).unwrap_or(0); - - let method = packed.meta.method; - if needs_xor_key(method) && self.resolve_key_for_meta(&packed.meta).is_none() { - return Err(Error::CorruptEntryTable( - "cannot resolve XOR key for packed resource", - )); - } - - decode_payload(&packed.packed, method, key16, packed.meta.unpacked_size) - } - - pub fn load_fast(&self, id: EntryId) -> Result<ResourceData<'_>> { - let entry = self.entry_by_id(id)?; - if entry.meta.method == PackMethod::None { - let packed = self.packed_slice(id, entry)?; - let size = - usize::try_from(entry.meta.unpacked_size).map_err(|_| Error::IntegerOverflow)?; - if packed.len() < size { - return Err(Error::OutputSizeMismatch { - expected: entry.meta.unpacked_size, - got: u32::try_from(packed.len()).unwrap_or(u32::MAX), - }); - } - return Ok(ResourceData::Borrowed(&packed[..size])); - } - Ok(ResourceData::Owned(self.load(id)?)) - } - - fn entry_by_id(&self, id: EntryId) -> Result<&EntryRecord> { - let idx = usize::try_from(id.0).map_err(|_| Error::IntegerOverflow)?; - self.entries - .get(idx) - .ok_or_else(|| Error::EntryIdOutOfRange { - id: id.0, - entry_count: self.entries.len().try_into().unwrap_or(u32::MAX), - }) - } - - fn packed_slice<'a>(&'a self, id: EntryId, entry: &EntryRecord) -> Result<&'a [u8]> { - let start = entry.effective_offset; - let end = start - .checked_add(entry.packed_size_available) - .ok_or(Error::IntegerOverflow)?; - self.bytes - .get(start..end) - .ok_or(Error::EntryDataOutOfBounds { - id: id.0, - offset: u64::try_from(start).unwrap_or(u64::MAX), - size: entry.packed_size_declared, - file_len: u64::try_from(self.bytes.len()).unwrap_or(u64::MAX), - }) - } - - fn resolve_key_for_meta(&self, meta: &EntryMeta) -> Option<u16> { - self.entries - .iter() - .find(|entry| { - entry.meta.name == meta.name - && entry.meta.flags == meta.flags - && entry.meta.data_offset == meta.data_offset - && entry.meta.packed_size == meta.packed_size - && entry.meta.unpacked_size == meta.unpacked_size - && entry.meta.method == meta.method - }) - .map(|entry| entry.key16) - } - - #[cfg(test)] - pub(crate) fn rebuild_from_parsed_metadata(&self) -> Result<Vec<u8>> { - let trailer_len = usize::from(self.trailer_raw.is_some()) * 6; - let pre_trailer_size = self - .source_size - .checked_sub(trailer_len) - .ok_or(Error::IntegerOverflow)?; - - let count = self.entries.len(); - let table_len = count.checked_mul(32).ok_or(Error::IntegerOverflow)?; - let table_end = 32usize - .checked_add(table_len) - .ok_or(Error::IntegerOverflow)?; - if pre_trailer_size < table_end { - return Err(Error::EntryTableOutOfBounds { - table_offset: 32, - table_len: u64::try_from(table_len).map_err(|_| Error::IntegerOverflow)?, - file_len: u64::try_from(pre_trailer_size).map_err(|_| Error::IntegerOverflow)?, - }); - } - - let mut out = vec![0u8; pre_trailer_size]; - out[0..32].copy_from_slice(&self.header_raw); - let encrypted_table = - xor_stream(&self.table_plain_original, (self.xor_seed & 0xFFFF) as u16); - out[32..table_end].copy_from_slice(&encrypted_table); - - let mut occupied = vec![false; pre_trailer_size]; - for byte in occupied.iter_mut().take(table_end) { - *byte = true; - } - - for (idx, entry) in self.entries.iter().enumerate() { - let packed = self - .load_packed(EntryId( - u32::try_from(idx).expect("entry count validated at parse"), - ))? - .packed; - let start = - usize::try_from(entry.data_offset_raw).map_err(|_| Error::IntegerOverflow)?; - for (offset, byte) in packed.iter().copied().enumerate() { - let pos = start.checked_add(offset).ok_or(Error::IntegerOverflow)?; - if pos >= out.len() { - return Err(Error::PackedSizePastEof { - id: u32::try_from(idx).expect("entry count validated at parse"), - offset: u64::from(entry.data_offset_raw), - packed_size: entry.packed_size_declared, - file_len: u64::try_from(out.len()).map_err(|_| Error::IntegerOverflow)?, - }); - } - if occupied[pos] && out[pos] != byte { - return Err(Error::CorruptEntryTable("packed payload overlap conflict")); - } - out[pos] = byte; - occupied[pos] = true; - } - } - - if let Some(trailer) = self.trailer_raw { - out.extend_from_slice(&trailer); - } - Ok(out) - } -} - -fn decode_payload( - packed: &[u8], - method: PackMethod, - key16: u16, - unpacked_size: u32, -) -> Result<Vec<u8>> { - let expected = usize::try_from(unpacked_size).map_err(|_| Error::IntegerOverflow)?; - - let out = match method { - PackMethod::None => { - if packed.len() < expected { - return Err(Error::OutputSizeMismatch { - expected: unpacked_size, - got: u32::try_from(packed.len()).unwrap_or(u32::MAX), - }); - } - packed[..expected].to_vec() - } - PackMethod::XorOnly => { - if packed.len() < expected { - return Err(Error::OutputSizeMismatch { - expected: unpacked_size, - got: u32::try_from(packed.len()).unwrap_or(u32::MAX), - }); - } - xor_stream(&packed[..expected], key16) - } - PackMethod::Lzss => lzss_decompress_simple(packed, expected, None)?, - PackMethod::XorLzss => { - // Optimized: XOR on-the-fly during decompression instead of creating temp buffer - lzss_decompress_simple(packed, expected, Some(key16))? - } - PackMethod::LzssHuffman => lzss_huffman_decompress(packed, expected, None)?, - PackMethod::XorLzssHuffman => { - // Optimized: XOR on-the-fly during decompression - lzss_huffman_decompress(packed, expected, Some(key16))? - } - PackMethod::Deflate => decode_deflate(packed)?, - PackMethod::Unknown(raw) => return Err(Error::UnsupportedMethod { raw }), - }; - - if out.len() != expected { - return Err(Error::OutputSizeMismatch { - expected: unpacked_size, - got: u32::try_from(out.len()).unwrap_or(u32::MAX), - }); - } - - Ok(out) -} - -fn needs_xor_key(method: PackMethod) -> bool { - matches!( - method, - PackMethod::XorOnly | PackMethod::XorLzss | PackMethod::XorLzssHuffman - ) -} - -#[cfg(test)] -mod tests; diff --git a/crates/rsli/src/parse.rs b/crates/rsli/src/parse.rs deleted file mode 100644 index 9a916dc..0000000 --- a/crates/rsli/src/parse.rs +++ /dev/null @@ -1,267 +0,0 @@ -use crate::compress::xor::xor_stream; -use crate::error::Error; -use crate::{EntryMeta, EntryRecord, Library, OpenOptions, PackMethod, Result}; -use std::cmp::Ordering; -use std::sync::Arc; - -pub fn parse_library(bytes: Arc<[u8]>, opts: OpenOptions) -> Result<Library> { - if bytes.len() < 32 { - return Err(Error::EntryTableOutOfBounds { - table_offset: 32, - table_len: 0, - file_len: u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?, - }); - } - - let mut header_raw = [0u8; 32]; - header_raw.copy_from_slice(&bytes[0..32]); - - if &bytes[0..2] != b"NL" { - let mut got = [0u8; 2]; - got.copy_from_slice(&bytes[0..2]); - return Err(Error::InvalidMagic { got }); - } - if bytes[3] != 0x01 { - return Err(Error::UnsupportedVersion { got: bytes[3] }); - } - - let entry_count = i16::from_le_bytes([bytes[4], bytes[5]]); - if entry_count < 0 { - return Err(Error::InvalidEntryCount { got: entry_count }); - } - let count = usize::try_from(entry_count).map_err(|_| Error::IntegerOverflow)?; - - // Validate entry_count fits in u32 (required for EntryId) - if count > u32::MAX as usize { - return Err(Error::TooManyEntries { got: count }); - } - - let xor_seed = u32::from_le_bytes([bytes[20], bytes[21], bytes[22], bytes[23]]); - - let table_len = count.checked_mul(32).ok_or(Error::IntegerOverflow)?; - let table_offset = 32usize; - let table_end = table_offset - .checked_add(table_len) - .ok_or(Error::IntegerOverflow)?; - if table_end > bytes.len() { - return Err(Error::EntryTableOutOfBounds { - table_offset: u64::try_from(table_offset).map_err(|_| Error::IntegerOverflow)?, - table_len: u64::try_from(table_len).map_err(|_| Error::IntegerOverflow)?, - file_len: u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?, - }); - } - - let table_enc = &bytes[table_offset..table_end]; - let table_plain_original = xor_stream(table_enc, (xor_seed & 0xFFFF) as u16); - if table_plain_original.len() != table_len { - return Err(Error::EntryTableDecryptFailed); - } - - let (overlay, trailer_raw) = parse_ao_trailer(&bytes, opts.allow_ao_trailer)?; - #[cfg(not(test))] - let _ = trailer_raw; - - let mut entries = Vec::with_capacity(count); - for idx in 0..count { - let row = &table_plain_original[idx * 32..(idx + 1) * 32]; - - let mut name_raw = [0u8; 12]; - name_raw.copy_from_slice(&row[0..12]); - - let flags_signed = i16::from_le_bytes([row[16], row[17]]); - let sort_to_original = i16::from_le_bytes([row[18], row[19]]); - let unpacked_size = u32::from_le_bytes([row[20], row[21], row[22], row[23]]); - let data_offset_raw = u32::from_le_bytes([row[24], row[25], row[26], row[27]]); - let packed_size_declared = u32::from_le_bytes([row[28], row[29], row[30], row[31]]); - - let method_raw = (flags_signed as u16 as u32) & 0x1E0; - let method = parse_method(method_raw); - - let effective_offset_u64 = u64::from(data_offset_raw) - .checked_add(u64::from(overlay)) - .ok_or(Error::IntegerOverflow)?; - let effective_offset = - usize::try_from(effective_offset_u64).map_err(|_| Error::IntegerOverflow)?; - - let packed_size_usize = - usize::try_from(packed_size_declared).map_err(|_| Error::IntegerOverflow)?; - let mut packed_size_available = packed_size_usize; - - let end = effective_offset_u64 - .checked_add(u64::from(packed_size_declared)) - .ok_or(Error::IntegerOverflow)?; - let file_len_u64 = u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?; - - if end > file_len_u64 { - if method_raw == 0x100 && end == file_len_u64 + 1 { - if opts.allow_deflate_eof_plus_one { - packed_size_available = packed_size_available - .checked_sub(1) - .ok_or(Error::IntegerOverflow)?; - } else { - return Err(Error::DeflateEofPlusOneQuirkRejected { - id: u32::try_from(idx).expect("entry count validated at parse"), - }); - } - } else { - return Err(Error::PackedSizePastEof { - id: u32::try_from(idx).expect("entry count validated at parse"), - offset: effective_offset_u64, - packed_size: packed_size_declared, - file_len: file_len_u64, - }); - } - } - - let available_end = effective_offset - .checked_add(packed_size_available) - .ok_or(Error::IntegerOverflow)?; - if available_end > bytes.len() { - return Err(Error::EntryDataOutOfBounds { - id: u32::try_from(idx).expect("entry count validated at parse"), - offset: effective_offset_u64, - size: packed_size_declared, - file_len: file_len_u64, - }); - } - - let name = decode_name(c_name_bytes(&name_raw)); - - entries.push(EntryRecord { - meta: EntryMeta { - name, - flags: i32::from(flags_signed), - method, - data_offset: effective_offset_u64, - packed_size: packed_size_declared, - unpacked_size, - }, - name_raw, - sort_to_original, - key16: sort_to_original as u16, - #[cfg(test)] - data_offset_raw, - packed_size_declared, - packed_size_available, - effective_offset, - }); - } - - let presorted_flag = u16::from_le_bytes([bytes[14], bytes[15]]); - if presorted_flag == 0xABBA { - let mut seen = vec![false; count]; - for entry in &entries { - let idx = i32::from(entry.sort_to_original); - if idx < 0 { - return Err(Error::CorruptEntryTable( - "sort_to_original is not a valid permutation index", - )); - } - let idx = usize::try_from(idx).map_err(|_| Error::IntegerOverflow)?; - if idx >= count { - return Err(Error::CorruptEntryTable( - "sort_to_original is not a valid permutation index", - )); - } - if seen[idx] { - return Err(Error::CorruptEntryTable( - "sort_to_original is not a permutation", - )); - } - seen[idx] = true; - } - if seen.iter().any(|value| !*value) { - return Err(Error::CorruptEntryTable( - "sort_to_original is not a permutation", - )); - } - } else { - let mut sorted: Vec<usize> = (0..count).collect(); - sorted.sort_by(|a, b| { - cmp_c_string( - c_name_bytes(&entries[*a].name_raw), - c_name_bytes(&entries[*b].name_raw), - ) - }); - for (idx, entry) in entries.iter_mut().enumerate() { - entry.sort_to_original = - i16::try_from(sorted[idx]).map_err(|_| Error::IntegerOverflow)?; - entry.key16 = entry.sort_to_original as u16; - } - } - - #[cfg(test)] - let source_size = bytes.len(); - - Ok(Library { - bytes, - entries, - #[cfg(test)] - header_raw, - #[cfg(test)] - table_plain_original, - #[cfg(test)] - xor_seed, - #[cfg(test)] - source_size, - #[cfg(test)] - trailer_raw, - }) -} - -fn parse_ao_trailer(bytes: &[u8], allow: bool) -> Result<(u32, Option<[u8; 6]>)> { - if !allow || bytes.len() < 6 { - return Ok((0, None)); - } - - if &bytes[bytes.len() - 6..bytes.len() - 4] != b"AO" { - return Ok((0, None)); - } - - let mut trailer = [0u8; 6]; - trailer.copy_from_slice(&bytes[bytes.len() - 6..]); - let overlay = u32::from_le_bytes([trailer[2], trailer[3], trailer[4], trailer[5]]); - - if u64::from(overlay) > u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)? { - return Err(Error::MediaOverlayOutOfBounds { - overlay, - file_len: u64::try_from(bytes.len()).map_err(|_| Error::IntegerOverflow)?, - }); - } - - Ok((overlay, Some(trailer))) -} - -pub fn parse_method(raw: u32) -> PackMethod { - match raw { - 0x000 => PackMethod::None, - 0x020 => PackMethod::XorOnly, - 0x040 => PackMethod::Lzss, - 0x060 => PackMethod::XorLzss, - 0x080 => PackMethod::LzssHuffman, - 0x0A0 => PackMethod::XorLzssHuffman, - 0x100 => PackMethod::Deflate, - other => PackMethod::Unknown(other), - } -} - -fn decode_name(name: &[u8]) -> String { - name.iter().map(|b| char::from(*b)).collect() -} - -pub fn c_name_bytes(raw: &[u8; 12]) -> &[u8] { - let len = raw.iter().position(|&b| b == 0).unwrap_or(raw.len()); - &raw[..len] -} - -pub fn cmp_c_string(a: &[u8], b: &[u8]) -> Ordering { - let min_len = a.len().min(b.len()); - let mut idx = 0usize; - while idx < min_len { - if a[idx] != b[idx] { - return a[idx].cmp(&b[idx]); - } - idx += 1; - } - a.len().cmp(&b.len()) -} diff --git a/crates/rsli/src/tests.rs b/crates/rsli/src/tests.rs deleted file mode 100644 index 07807d3..0000000 --- a/crates/rsli/src/tests.rs +++ /dev/null @@ -1,1337 +0,0 @@ -use super::*; -use crate::compress::lzh::{LZH_MAX_FREQ, LZH_N_CHAR, LZH_R, LZH_T}; -use crate::compress::xor::xor_stream; -use flate2::write::DeflateEncoder; -use flate2::write::ZlibEncoder; -use flate2::Compression; -use std::any::Any; -use std::fs; -use std::io::Write as _; -use std::panic::{catch_unwind, AssertUnwindSafe}; -use std::path::PathBuf; - -#[derive(Clone, Debug)] -struct SyntheticRsliEntry { - name: String, - method_raw: u16, - plain: Vec<u8>, - declared_packed_size: Option<u32>, -} - -#[derive(Clone, Debug)] -struct RsliBuildOptions { - seed: u32, - presorted: bool, - overlay: u32, - add_ao_trailer: bool, -} - -impl Default for RsliBuildOptions { - fn default() -> Self { - Self { - seed: 0x1234_5678, - presorted: true, - overlay: 0, - add_ao_trailer: false, - } - } -} - -fn collect_files_recursive(root: &Path, out: &mut Vec<PathBuf>) { - let Ok(entries) = fs::read_dir(root) else { - return; - }; - for entry in entries.flatten() { - let path = entry.path(); - if path.is_dir() { - collect_files_recursive(&path, out); - } else if path.is_file() { - out.push(path); - } - } -} - -fn rsli_test_files() -> Vec<PathBuf> { - let root = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("..") - .join("..") - .join("testdata") - .join("rsli"); - let mut files = Vec::new(); - collect_files_recursive(&root, &mut files); - files.sort(); - files - .into_iter() - .filter(|path| { - fs::read(path) - .map(|data| data.get(0..4) == Some(b"NL\0\x01")) - .unwrap_or(false) - }) - .collect() -} - -fn panic_message(payload: Box<dyn Any + Send>) -> String { - let any = payload.as_ref(); - if let Some(message) = any.downcast_ref::<String>() { - return message.clone(); - } - if let Some(message) = any.downcast_ref::<&str>() { - return (*message).to_string(); - } - String::from("panic without message") -} - -fn write_temp_file(prefix: &str, bytes: &[u8]) -> PathBuf { - let mut path = std::env::temp_dir(); - path.push(format!( - "{}-{}-{}.bin", - prefix, - std::process::id(), - std::time::SystemTime::now() - .duration_since(std::time::UNIX_EPOCH) - .map(|d| d.as_nanos()) - .unwrap_or(0) - )); - fs::write(&path, bytes).expect("failed to write temp archive"); - path -} - -fn deflate_raw(data: &[u8]) -> Vec<u8> { - let mut encoder = DeflateEncoder::new(Vec::new(), Compression::default()); - encoder - .write_all(data) - .expect("deflate encoder write failed"); - encoder.finish().expect("deflate encoder finish failed") -} - -fn deflate_zlib(data: &[u8]) -> Vec<u8> { - let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default()); - encoder.write_all(data).expect("zlib encoder write failed"); - encoder.finish().expect("zlib encoder finish failed") -} - -fn lzss_pack_literals(data: &[u8]) -> Vec<u8> { - let mut out = Vec::new(); - for chunk in data.chunks(8) { - let mask = if chunk.len() == 8 { - 0xFF - } else { - (1u16 - .checked_shl(u32::try_from(chunk.len()).expect("chunk len overflow")) - .expect("shift overflow") - - 1) as u8 - }; - out.push(mask); - out.extend_from_slice(chunk); - } - out -} - -struct BitWriter { - bytes: Vec<u8>, - current: u8, - mask: u8, -} - -impl BitWriter { - fn new() -> Self { - Self { - bytes: Vec::new(), - current: 0, - mask: 0x80, - } - } - - fn write_bit(&mut self, bit: u8) { - if bit != 0 { - self.current |= self.mask; - } - self.mask >>= 1; - if self.mask == 0 { - self.bytes.push(self.current); - self.current = 0; - self.mask = 0x80; - } - } - - fn finish(mut self) -> Vec<u8> { - if self.mask != 0x80 { - self.bytes.push(self.current); - } - self.bytes - } -} - -struct LzhLiteralModel { - freq: [u16; LZH_T + 1], - parent: [usize; LZH_T + LZH_N_CHAR], - son: [usize; LZH_T + 1], -} - -impl LzhLiteralModel { - fn new() -> Self { - let mut model = Self { - freq: [0; LZH_T + 1], - parent: [0; LZH_T + LZH_N_CHAR], - son: [0; LZH_T + 1], - }; - model.start_huff(); - model - } - - fn encode_literal(&mut self, literal: u8, writer: &mut BitWriter) { - let target = usize::from(literal) + LZH_T; - let mut path = Vec::new(); - let mut visited = [false; LZH_T + 1]; - let found = self.find_path(self.son[LZH_R], target, &mut path, &mut visited); - assert!(found, "failed to encode literal {literal}"); - for bit in path { - writer.write_bit(bit); - } - - self.update(usize::from(literal)); - } - - fn find_path( - &self, - node: usize, - target: usize, - path: &mut Vec<u8>, - visited: &mut [bool; LZH_T + 1], - ) -> bool { - if node == target { - return true; - } - if node >= LZH_T { - return false; - } - if visited[node] { - return false; - } - visited[node] = true; - - for bit in [0u8, 1u8] { - let child = self.son[node + usize::from(bit)]; - path.push(bit); - if self.find_path(child, target, path, visited) { - visited[node] = false; - return true; - } - path.pop(); - } - - visited[node] = false; - false - } - - fn start_huff(&mut self) { - for i in 0..LZH_N_CHAR { - self.freq[i] = 1; - self.son[i] = i + LZH_T; - self.parent[i + LZH_T] = i; - } - - let mut i = 0usize; - let mut j = LZH_N_CHAR; - while j <= LZH_R { - self.freq[j] = self.freq[i].saturating_add(self.freq[i + 1]); - self.son[j] = i; - self.parent[i] = j; - self.parent[i + 1] = j; - i += 2; - j += 1; - } - - self.freq[LZH_T] = u16::MAX; - self.parent[LZH_R] = 0; - } - - fn update(&mut self, c: usize) { - if self.freq[LZH_R] == LZH_MAX_FREQ { - self.reconstruct(); - } - - let mut current = self.parent[c + LZH_T]; - loop { - self.freq[current] = self.freq[current].saturating_add(1); - let freq = self.freq[current]; - - if current + 1 < self.freq.len() && freq > self.freq[current + 1] { - let mut swap_idx = current + 1; - while swap_idx + 1 < self.freq.len() && freq > self.freq[swap_idx + 1] { - swap_idx += 1; - } - - self.freq.swap(current, swap_idx); - - let left = self.son[current]; - let right = self.son[swap_idx]; - self.son[current] = right; - self.son[swap_idx] = left; - - self.parent[left] = swap_idx; - if left < LZH_T { - self.parent[left + 1] = swap_idx; - } - - self.parent[right] = current; - if right < LZH_T { - self.parent[right + 1] = current; - } - - current = swap_idx; - } - - current = self.parent[current]; - if current == 0 { - break; - } - } - } - - fn reconstruct(&mut self) { - let mut j = 0usize; - for i in 0..LZH_T { - if self.son[i] >= LZH_T { - self.freq[j] = self.freq[i].div_ceil(2); - self.son[j] = self.son[i]; - j += 1; - } - } - - let mut i = 0usize; - let mut current = LZH_N_CHAR; - while current < LZH_T { - let sum = self.freq[i].saturating_add(self.freq[i + 1]); - self.freq[current] = sum; - - let mut insert_at = current; - while insert_at > 0 && sum < self.freq[insert_at - 1] { - insert_at -= 1; - } - - for move_idx in (insert_at..current).rev() { - self.freq[move_idx + 1] = self.freq[move_idx]; - self.son[move_idx + 1] = self.son[move_idx]; - } - - self.freq[insert_at] = sum; - self.son[insert_at] = i; - i += 2; - current += 1; - } - - for idx in 0..LZH_T { - let node = self.son[idx]; - self.parent[node] = idx; - if node < LZH_T { - self.parent[node + 1] = idx; - } - } - - self.freq[LZH_T] = u16::MAX; - self.parent[LZH_R] = 0; - } -} - -fn lzh_pack_literals(data: &[u8]) -> Vec<u8> { - let mut writer = BitWriter::new(); - let mut model = LzhLiteralModel::new(); - for byte in data { - model.encode_literal(*byte, &mut writer); - } - writer.finish() -} - -fn packed_for_method(method_raw: u16, plain: &[u8], key16: u16) -> Vec<u8> { - match (u32::from(method_raw)) & 0x1E0 { - 0x000 => plain.to_vec(), - 0x020 => xor_stream(plain, key16), - 0x040 => lzss_pack_literals(plain), - 0x060 => xor_stream(&lzss_pack_literals(plain), key16), - 0x080 => lzh_pack_literals(plain), - 0x0A0 => xor_stream(&lzh_pack_literals(plain), key16), - 0x100 => deflate_raw(plain), - _ => plain.to_vec(), - } -} - -fn build_rsli_bytes(entries: &[SyntheticRsliEntry], opts: &RsliBuildOptions) -> Vec<u8> { - let count = entries.len(); - let mut rows_plain = vec![0u8; count * 32]; - let table_end = 32 + rows_plain.len(); - - let mut sort_lookup: Vec<usize> = (0..count).collect(); - sort_lookup.sort_by(|a, b| entries[*a].name.as_bytes().cmp(entries[*b].name.as_bytes())); - - let mut packed_blobs = Vec::with_capacity(count); - for index in 0..count { - let key16 = u16::try_from(sort_lookup[index]).expect("sort index overflow"); - let packed = packed_for_method(entries[index].method_raw, &entries[index].plain, key16); - packed_blobs.push(packed); - } - - let overlay = usize::try_from(opts.overlay).expect("overlay overflow"); - let mut cursor = table_end + overlay; - let mut output = vec![0u8; cursor]; - - let mut data_offsets = Vec::with_capacity(count); - for (index, packed) in packed_blobs.iter().enumerate() { - let raw_offset = cursor - .checked_sub(overlay) - .expect("overlay larger than cursor"); - data_offsets.push(raw_offset); - - let end = cursor.checked_add(packed.len()).expect("cursor overflow"); - if output.len() < end { - output.resize(end, 0); - } - output[cursor..end].copy_from_slice(packed); - cursor = end; - - let base = index * 32; - let mut name_raw = [0u8; 12]; - let uppercase = entries[index].name.to_ascii_uppercase(); - let name_bytes = uppercase.as_bytes(); - assert!(name_bytes.len() <= 12, "name too long in synthetic fixture"); - name_raw[..name_bytes.len()].copy_from_slice(name_bytes); - - rows_plain[base..base + 12].copy_from_slice(&name_raw); - - let sort_field: i16 = if opts.presorted { - i16::try_from(sort_lookup[index]).expect("sort field overflow") - } else { - 0 - }; - - let packed_size = entries[index] - .declared_packed_size - .unwrap_or_else(|| u32::try_from(packed.len()).expect("packed size overflow")); - - rows_plain[base + 16..base + 18].copy_from_slice(&entries[index].method_raw.to_le_bytes()); - rows_plain[base + 18..base + 20].copy_from_slice(&sort_field.to_le_bytes()); - rows_plain[base + 20..base + 24].copy_from_slice( - &u32::try_from(entries[index].plain.len()) - .expect("unpacked size overflow") - .to_le_bytes(), - ); - rows_plain[base + 24..base + 28].copy_from_slice( - &u32::try_from(data_offsets[index]) - .expect("data offset overflow") - .to_le_bytes(), - ); - rows_plain[base + 28..base + 32].copy_from_slice(&packed_size.to_le_bytes()); - } - - if output.len() < table_end { - output.resize(table_end, 0); - } - - output[0..2].copy_from_slice(b"NL"); - output[2] = 0; - output[3] = 1; - output[4..6].copy_from_slice( - &i16::try_from(count) - .expect("entry count overflow") - .to_le_bytes(), - ); - - let presorted_flag = if opts.presorted { 0xABBA_u16 } else { 0_u16 }; - output[14..16].copy_from_slice(&presorted_flag.to_le_bytes()); - output[20..24].copy_from_slice(&opts.seed.to_le_bytes()); - - let encrypted_table = xor_stream(&rows_plain, (opts.seed & 0xFFFF) as u16); - output[32..table_end].copy_from_slice(&encrypted_table); - - if opts.add_ao_trailer { - output.extend_from_slice(b"AO"); - output.extend_from_slice(&opts.overlay.to_le_bytes()); - } - - output -} - -fn read_u32_le(bytes: &[u8], offset: usize) -> u32 { - let slice = bytes - .get(offset..offset + 4) - .expect("u32 read out of bounds in test"); - let arr: [u8; 4] = slice.try_into().expect("u32 conversion failed in test"); - u32::from_le_bytes(arr) -} - -#[test] -fn rsli_read_unpack_and_repack_all_files() { - let files = rsli_test_files(); - if files.is_empty() { - eprintln!( - "skipping rsli_read_unpack_and_repack_all_files: no RsLi archives in testdata/rsli" - ); - return; - } - - let checked = files.len(); - let mut success = 0usize; - let mut failures = Vec::new(); - - for path in files { - let display_path = path.display().to_string(); - let result = catch_unwind(AssertUnwindSafe(|| { - let original = fs::read(&path).expect("failed to read archive"); - let library = Library::open_path(&path) - .unwrap_or_else(|err| panic!("failed to open {}: {err}", path.display())); - - let count = library.entry_count(); - assert_eq!( - count, - library.entries().count(), - "entry count mismatch: {}", - path.display() - ); - - for idx in 0..count { - let id = EntryId(idx as u32); - let meta_ref = library - .get(id) - .unwrap_or_else(|| panic!("missing entry #{idx} in {}", path.display())); - - let loaded = library.load(id).unwrap_or_else(|err| { - panic!("load failed for {} entry #{idx}: {err}", path.display()) - }); - - let packed = library.load_packed(id).unwrap_or_else(|err| { - panic!( - "load_packed failed for {} entry #{idx}: {err}", - path.display() - ) - }); - let unpacked = library.unpack(&packed).unwrap_or_else(|err| { - panic!("unpack failed for {} entry #{idx}: {err}", path.display()) - }); - assert_eq!( - loaded, - unpacked, - "load != unpack in {} entry #{idx}", - path.display() - ); - - let mut out = Vec::new(); - let written = library.load_into(id, &mut out).unwrap_or_else(|err| { - panic!( - "load_into failed for {} entry #{idx}: {err}", - path.display() - ) - }); - assert_eq!( - written, - loaded.len(), - "load_into size mismatch in {} entry #{idx}", - path.display() - ); - assert_eq!( - out, - loaded, - "load_into payload mismatch in {} entry #{idx}", - path.display() - ); - - let fast = library.load_fast(id).unwrap_or_else(|err| { - panic!( - "load_fast failed for {} entry #{idx}: {err}", - path.display() - ) - }); - assert_eq!( - fast.as_slice(), - loaded.as_slice(), - "load_fast mismatch in {} entry #{idx}", - path.display() - ); - - let found = library.find(&meta_ref.meta.name).unwrap_or_else(|| { - panic!( - "find failed for '{}' in {}", - meta_ref.meta.name, - path.display() - ) - }); - let found_meta = library.get(found).expect("find returned invalid entry id"); - assert_eq!( - found_meta.meta.name, - meta_ref.meta.name, - "find returned a different entry in {}", - path.display() - ); - } - - let rebuilt = library - .rebuild_from_parsed_metadata() - .unwrap_or_else(|err| panic!("rebuild failed for {}: {err}", path.display())); - assert_eq!( - rebuilt, - original, - "byte-to-byte roundtrip mismatch for {}", - path.display() - ); - })); - - match result { - Ok(()) => success += 1, - Err(payload) => failures.push(format!("{}: {}", display_path, panic_message(payload))), - } - } - - let failed = failures.len(); - eprintln!( - "RsLi summary: checked={}, success={}, failed={}", - checked, success, failed - ); - if !failures.is_empty() { - panic!( - "RsLi validation failed.\nsummary: checked={}, success={}, failed={}\n{}", - checked, - success, - failed, - failures.join("\n") - ); - } -} - -#[test] -fn rsli_docs_structural_invariants_all_files() { - let files = rsli_test_files(); - if files.is_empty() { - eprintln!( - "skipping rsli_docs_structural_invariants_all_files: no RsLi archives in testdata/rsli" - ); - return; - } - - let mut deflate_eof_plus_one_quirks = Vec::new(); - - for path in files { - let bytes = fs::read(&path).unwrap_or_else(|err| { - panic!("failed to read {}: {err}", path.display()); - }); - - assert!( - bytes.len() >= 32, - "RsLi header too short in {}", - path.display() - ); - assert_eq!(&bytes[0..2], b"NL", "bad magic in {}", path.display()); - assert_eq!( - bytes[2], - 0, - "reserved header byte must be zero in {}", - path.display() - ); - assert_eq!(bytes[3], 1, "bad version in {}", path.display()); - - let entry_count = i16::from_le_bytes([bytes[4], bytes[5]]); - assert!( - entry_count >= 0, - "negative entry_count={} in {}", - entry_count, - path.display() - ); - let count = usize::try_from(entry_count).expect("entry_count overflow"); - let table_size = count.checked_mul(32).expect("table_size overflow"); - let table_end = 32usize.checked_add(table_size).expect("table_end overflow"); - assert!( - table_end <= bytes.len(), - "table out of bounds in {}", - path.display() - ); - - let seed = read_u32_le(&bytes, 20); - let table_plain = xor_stream(&bytes[32..table_end], (seed & 0xFFFF) as u16); - assert_eq!( - table_plain.len(), - table_size, - "decrypted table size mismatch in {}", - path.display() - ); - - let mut overlay = 0u32; - if bytes.len() >= 6 && &bytes[bytes.len() - 6..bytes.len() - 4] == b"AO" { - overlay = read_u32_le(&bytes, bytes.len() - 4); - assert!( - usize::try_from(overlay).expect("overlay overflow") <= bytes.len(), - "overlay beyond EOF in {}", - path.display() - ); - } - - let presorted_flag = u16::from_le_bytes([bytes[14], bytes[15]]); - let mut sort_values = Vec::with_capacity(count); - - for index in 0..count { - let base = index * 32; - let row = &table_plain[base..base + 32]; - let flags_signed = i16::from_le_bytes([row[16], row[17]]); - let sort_to_original = i16::from_le_bytes([row[18], row[19]]); - let data_offset = u64::from(read_u32_le(row, 24)); - let packed_size = u64::from(read_u32_le(row, 28)); - - let method = (flags_signed as u16 as u32) & 0x1E0; - let effective_offset = data_offset + u64::from(overlay); - let end = effective_offset + packed_size; - let file_len = u64::try_from(bytes.len()).expect("file size overflow"); - - if end > file_len { - assert!( - method == 0x100 && end == file_len + 1, - "packed range out of bounds in {} entry #{index}: method=0x{method:03X}, range=[{effective_offset}, {end}), file={file_len}", - path.display() - ); - deflate_eof_plus_one_quirks.push((path.display().to_string(), index)); - } - - sort_values.push(sort_to_original); - } - - if presorted_flag == 0xABBA { - let mut sorted = sort_values; - sorted.sort_unstable(); - let expected: Vec<i16> = (0..count) - .map(|idx| i16::try_from(idx).expect("too many entries for i16")) - .collect(); - assert_eq!( - sorted, - expected, - "sort_to_original is not a permutation in {}", - path.display() - ); - } - } - - if !deflate_eof_plus_one_quirks.is_empty() { - assert!( - deflate_eof_plus_one_quirks - .iter() - .all(|(file, idx)| file.ends_with("sprites.lib") && *idx == 23), - "unexpected deflate EOF+1 quirks: {:?}", - deflate_eof_plus_one_quirks - ); - } -} - -#[test] -fn rsli_synthetic_all_methods_roundtrip() { - let entries = vec![ - SyntheticRsliEntry { - name: "M_NONE".to_string(), - method_raw: 0x000, - plain: b"plain-data".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_XOR".to_string(), - method_raw: 0x020, - plain: b"xor-only".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_LZSS".to_string(), - method_raw: 0x040, - plain: b"lzss literals payload".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_XLZS".to_string(), - method_raw: 0x060, - plain: b"xor lzss payload".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_LZHU".to_string(), - method_raw: 0x080, - plain: b"huffman literals payload".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_XLZH".to_string(), - method_raw: 0x0A0, - plain: b"xor huffman payload".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "M_DEFL".to_string(), - method_raw: 0x100, - plain: b"deflate payload with repetition repetition repetition".to_vec(), - declared_packed_size: None, - }, - ]; - - let bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - seed: 0xA1B2_C3D4, - presorted: false, - overlay: 0, - add_ao_trailer: false, - }, - ); - let path = write_temp_file("rsli-all-methods", &bytes); - - let library = Library::open_path(&path).expect("open synthetic rsli failed"); - assert_eq!(library.entry_count(), entries.len()); - - for entry in &entries { - let id = library - .find(&entry.name) - .unwrap_or_else(|| panic!("find failed for {}", entry.name)); - let loaded = library - .load(id) - .unwrap_or_else(|err| panic!("load failed for {}: {err}", entry.name)); - assert_eq!( - loaded, entry.plain, - "decoded payload mismatch for {}", - entry.name - ); - - let packed = library - .load_packed(id) - .unwrap_or_else(|err| panic!("load_packed failed for {}: {err}", entry.name)); - let unpacked = library - .unpack(&packed) - .unwrap_or_else(|err| panic!("unpack failed for {}: {err}", entry.name)); - assert_eq!(unpacked, entry.plain, "unpack mismatch for {}", entry.name); - } - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_empty_archive_roundtrip() { - let bytes = build_rsli_bytes(&[], &RsliBuildOptions::default()); - let path = write_temp_file("rsli-empty", &bytes); - - let library = Library::open_path(&path).expect("open empty rsli failed"); - assert_eq!(library.entry_count(), 0); - assert_eq!(library.find("ANYTHING"), None); - - let rebuilt = library - .rebuild_from_parsed_metadata() - .expect("rebuild empty rsli failed"); - assert_eq!(rebuilt, bytes, "empty rsli roundtrip mismatch"); - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_max_name_length_without_nul_roundtrip() { - let max_name = "NAME12345678"; - assert_eq!(max_name.len(), 12); - - let bytes = build_rsli_bytes( - &[SyntheticRsliEntry { - name: max_name.to_string(), - method_raw: 0x000, - plain: b"payload".to_vec(), - declared_packed_size: None, - }], - &RsliBuildOptions::default(), - ); - let path = write_temp_file("rsli-max-name", &bytes); - - let library = Library::open_path(&path).expect("open max-name rsli failed"); - assert_eq!(library.entry_count(), 1); - assert_eq!(library.find(max_name), Some(EntryId(0))); - assert_eq!( - library.find(&max_name.to_ascii_lowercase()), - Some(EntryId(0)) - ); - assert_eq!( - library.entries[0] - .name_raw - .iter() - .position(|byte| *byte == 0), - None, - "name_raw must occupy full 12 bytes without NUL" - ); - - let entry = library.get(EntryId(0)).expect("missing entry"); - assert_eq!(entry.meta.name, max_name); - assert_eq!( - library.load(EntryId(0)).expect("load failed"), - b"payload", - "payload mismatch" - ); - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_lzss_large_payload_over_4k_roundtrip() { - let plain: Vec<u8> = (0..10_000u32).map(|v| (v % 251) as u8).collect(); - let entries = vec![ - SyntheticRsliEntry { - name: "LZSS4K".to_string(), - method_raw: 0x040, - plain: plain.clone(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "XLZS4K".to_string(), - method_raw: 0x060, - plain: plain.clone(), - declared_packed_size: None, - }, - ]; - let bytes = build_rsli_bytes(&entries, &RsliBuildOptions::default()); - let path = write_temp_file("rsli-lzss-4k", &bytes); - - let library = Library::open_path(&path).expect("open large-lzss rsli failed"); - assert_eq!(library.entry_count(), entries.len()); - - for entry in &entries { - let id = library - .find(&entry.name) - .unwrap_or_else(|| panic!("find failed for {}", entry.name)); - let loaded = library - .load(id) - .unwrap_or_else(|err| panic!("load failed for {}: {err}", entry.name)); - assert_eq!(loaded, plain, "payload mismatch for {}", entry.name); - } - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_find_falls_back_when_sort_table_corrupted_in_memory() { - let entries = vec![ - SyntheticRsliEntry { - name: "AAA".to_string(), - method_raw: 0x000, - plain: b"a".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "BBB".to_string(), - method_raw: 0x000, - plain: b"b".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "CCC".to_string(), - method_raw: 0x000, - plain: b"c".to_vec(), - declared_packed_size: None, - }, - ]; - let bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - presorted: true, - ..RsliBuildOptions::default() - }, - ); - let path = write_temp_file("rsli-find-fallback", &bytes); - - let mut library = Library::open_path(&path).expect("open synthetic rsli failed"); - library.entries[1].sort_to_original = -1; - - assert_eq!(library.find("AAA"), Some(EntryId(0))); - assert_eq!(library.find("bbb"), Some(EntryId(1))); - assert_eq!(library.find("CcC"), Some(EntryId(2))); - assert_eq!(library.find("missing"), None); - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_deflate_method_rejects_zlib_wrapped_stream() { - let plain = b"payload".to_vec(); - let zlib_payload = deflate_zlib(&plain); - let entries = vec![SyntheticRsliEntry { - name: "ZLIB".to_string(), - method_raw: 0x100, - plain, - declared_packed_size: Some( - u32::try_from(zlib_payload.len()).expect("zlib payload size overflow"), - ), - }]; - let mut bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - presorted: true, - ..RsliBuildOptions::default() - }, - ); - - let table_end = 32 + entries.len() * 32; - let data_offset = table_end; - let data_end = data_offset + zlib_payload.len(); - if bytes.len() < data_end { - bytes.resize(data_end, 0); - } - bytes[data_offset..data_end].copy_from_slice(&zlib_payload); - - let path = write_temp_file("rsli-zlib-reject", &bytes); - let library = Library::open_path(&path).expect("open zlib-wrapped rsli failed"); - match library.load(EntryId(0)) { - Err(Error::DecompressionFailed(reason)) => { - assert_eq!(reason, "deflate"); - } - other => panic!("expected deflate decompression error, got {other:?}"), - } - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_lzss_huffman_reports_unexpected_eof() { - let entries = vec![SyntheticRsliEntry { - name: "TRUNC".to_string(), - method_raw: 0x080, - plain: b"this payload is long enough".to_vec(), - declared_packed_size: None, - }]; - let mut bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - presorted: true, - ..RsliBuildOptions::default() - }, - ); - - let seed = read_u32_le(&bytes, 20); - let mut table_plain = xor_stream(&bytes[32..64], (seed & 0xFFFF) as u16); - let original_packed_size = u32::from_le_bytes([ - table_plain[28], - table_plain[29], - table_plain[30], - table_plain[31], - ]); - assert!( - original_packed_size > 4, - "packed payload too small for truncation" - ); - let truncated_size = original_packed_size - 3; - table_plain[28..32].copy_from_slice(&truncated_size.to_le_bytes()); - let encrypted_table = xor_stream(&table_plain, (seed & 0xFFFF) as u16); - bytes[32..64].copy_from_slice(&encrypted_table); - - let path = write_temp_file("rsli-lzh-truncated", &bytes); - let library = Library::open_path(&path).expect("open truncated lzh rsli failed"); - match library.load(EntryId(0)) { - Err(Error::DecompressionFailed(reason)) => { - assert_eq!(reason, "lzss-huffman: unexpected EOF"); - } - other => panic!("expected lzss-huffman EOF error, got {other:?}"), - } - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_presorted_flag_requires_permutation() { - let entries = vec![ - SyntheticRsliEntry { - name: "AAA".to_string(), - method_raw: 0x000, - plain: b"a".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "BBB".to_string(), - method_raw: 0x000, - plain: b"b".to_vec(), - declared_packed_size: None, - }, - ]; - let mut bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - presorted: true, - ..RsliBuildOptions::default() - }, - ); - - let seed = read_u32_le(&bytes, 20); - let mut table_plain = xor_stream(&bytes[32..32 + entries.len() * 32], (seed & 0xFFFF) as u16); - - // Corrupt sort_to_original: duplicate index 0, so the table is not a permutation. - table_plain[18..20].copy_from_slice(&0i16.to_le_bytes()); - table_plain[50..52].copy_from_slice(&0i16.to_le_bytes()); - - let table_encrypted = xor_stream(&table_plain, (seed & 0xFFFF) as u16); - bytes[32..32 + table_encrypted.len()].copy_from_slice(&table_encrypted); - - let path = write_temp_file("rsli-bad-presorted-perm", &bytes); - match Library::open_path(&path) { - Err(Error::CorruptEntryTable(message)) => { - assert!( - message.contains("permutation"), - "unexpected error message: {message}" - ); - } - other => panic!("expected CorruptEntryTable for invalid permutation, got {other:?}"), - } - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_load_reports_correct_entry_id_on_range_failure() { - let entries = vec![ - SyntheticRsliEntry { - name: "ONE".to_string(), - method_raw: 0x000, - plain: b"one".to_vec(), - declared_packed_size: None, - }, - SyntheticRsliEntry { - name: "TWO".to_string(), - method_raw: 0x000, - plain: b"two".to_vec(), - declared_packed_size: None, - }, - ]; - let bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - presorted: true, - ..RsliBuildOptions::default() - }, - ); - let path = write_temp_file("rsli-entry-id-error", &bytes); - - let mut library = Library::open_path(&path).expect("open synthetic rsli failed"); - library.entries[1].packed_size_available = usize::MAX; - - match library.load(EntryId(1)) { - Err(Error::IntegerOverflow) => {} - other => panic!("expected IntegerOverflow, got {other:?}"), - } - - library.entries[1].packed_size_available = library.bytes.len(); - match library.load(EntryId(1)) { - Err(Error::EntryDataOutOfBounds { id, .. }) => assert_eq!(id, 1), - other => panic!("expected EntryDataOutOfBounds with id=1, got {other:?}"), - } - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_xorlzss_huffman_on_the_fly_roundtrip() { - let plain: Vec<u8> = (0..512u16).map(|i| b'A' + (i % 26) as u8).collect(); - let entries = vec![SyntheticRsliEntry { - name: "XLZH_ONFLY".to_string(), - method_raw: 0x0A0, - plain: plain.clone(), - declared_packed_size: None, - }]; - - let bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - seed: 0x0BAD_C0DE, - presorted: true, - overlay: 0, - add_ao_trailer: false, - }, - ); - let path = write_temp_file("rsli-xorlzh-onfly", &bytes); - - let library = Library::open_path(&path).expect("open synthetic XLZH archive failed"); - let id = library - .find("XLZH_ONFLY") - .expect("find XLZH_ONFLY entry failed"); - - let loaded = library.load(id).expect("load XLZH_ONFLY failed"); - assert_eq!(loaded, plain); - - let packed = library - .load_packed(id) - .expect("load_packed XLZH_ONFLY failed"); - let unpacked = library.unpack(&packed).expect("unpack XLZH_ONFLY failed"); - assert_eq!(unpacked, loaded); - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_synthetic_overlay_and_ao_trailer() { - let entries = vec![SyntheticRsliEntry { - name: "OVERLAY".to_string(), - method_raw: 0x040, - plain: b"overlay-data".to_vec(), - declared_packed_size: None, - }]; - - let bytes = build_rsli_bytes( - &entries, - &RsliBuildOptions { - seed: 0x4433_2211, - presorted: true, - overlay: 128, - add_ao_trailer: true, - }, - ); - let path = write_temp_file("rsli-overlay", &bytes); - - let library = Library::open_path_with( - &path, - OpenOptions { - allow_ao_trailer: true, - allow_deflate_eof_plus_one: true, - }, - ) - .expect("open with AO trailer enabled failed"); - - let id = library.find("OVERLAY").expect("find overlay entry failed"); - let payload = library.load(id).expect("load overlay entry failed"); - assert_eq!(payload, b"overlay-data"); - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_deflate_eof_plus_one_quirk() { - let plain = b"quirk deflate payload".to_vec(); - let packed = deflate_raw(&plain); - let declared = u32::try_from(packed.len() + 1).expect("declared size overflow"); - - let entries = vec![SyntheticRsliEntry { - name: "QUIRK".to_string(), - method_raw: 0x100, - plain, - declared_packed_size: Some(declared), - }]; - let bytes = build_rsli_bytes(&entries, &RsliBuildOptions::default()); - let path = write_temp_file("rsli-deflate-quirk", &bytes); - - let lib_ok = Library::open_path_with( - &path, - OpenOptions { - allow_ao_trailer: true, - allow_deflate_eof_plus_one: true, - }, - ) - .expect("open with EOF+1 quirk enabled failed"); - let loaded = lib_ok - .load(lib_ok.find("QUIRK").expect("find quirk entry failed")) - .expect("load quirk entry failed"); - assert_eq!(loaded, b"quirk deflate payload"); - - match Library::open_path_with( - &path, - OpenOptions { - allow_ao_trailer: true, - allow_deflate_eof_plus_one: false, - }, - ) { - Err(Error::DeflateEofPlusOneQuirkRejected { id }) => assert_eq!(id, 0), - other => panic!("expected DeflateEofPlusOneQuirkRejected, got {other:?}"), - } - - let _ = fs::remove_file(&path); -} - -#[test] -fn rsli_validation_error_cases() { - let valid = build_rsli_bytes( - &[SyntheticRsliEntry { - name: "BASE".to_string(), - method_raw: 0x000, - plain: b"abc".to_vec(), - declared_packed_size: None, - }], - &RsliBuildOptions::default(), - ); - - let mut bad_magic = valid.clone(); - bad_magic[0..2].copy_from_slice(b"XX"); - let path = write_temp_file("rsli-bad-magic", &bad_magic); - match Library::open_path(&path) { - Err(Error::InvalidMagic { .. }) => {} - other => panic!("expected InvalidMagic, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut bad_version = valid.clone(); - bad_version[3] = 2; - let path = write_temp_file("rsli-bad-version", &bad_version); - match Library::open_path(&path) { - Err(Error::UnsupportedVersion { got }) => assert_eq!(got, 2), - other => panic!("expected UnsupportedVersion, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut bad_count = valid.clone(); - bad_count[4..6].copy_from_slice(&(-1_i16).to_le_bytes()); - let path = write_temp_file("rsli-bad-count", &bad_count); - match Library::open_path(&path) { - Err(Error::InvalidEntryCount { got }) => assert_eq!(got, -1), - other => panic!("expected InvalidEntryCount, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut bad_table = valid.clone(); - bad_table[4..6].copy_from_slice(&100_i16.to_le_bytes()); - let path = write_temp_file("rsli-bad-table", &bad_table); - match Library::open_path(&path) { - Err(Error::EntryTableOutOfBounds { .. }) => {} - other => panic!("expected EntryTableOutOfBounds, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut unknown_method = build_rsli_bytes( - &[SyntheticRsliEntry { - name: "UNK".to_string(), - method_raw: 0x120, - plain: b"x".to_vec(), - declared_packed_size: None, - }], - &RsliBuildOptions::default(), - ); - // Force truly unknown method by writing 0x1C0 mask bits. - let row = 32; - unknown_method[row + 16..row + 18].copy_from_slice(&(0x1C0_u16).to_le_bytes()); - // Re-encrypt table with the same seed. - let seed = u32::from_le_bytes([ - unknown_method[20], - unknown_method[21], - unknown_method[22], - unknown_method[23], - ]); - let mut plain_row = vec![0u8; 32]; - plain_row.copy_from_slice(&unknown_method[32..64]); - plain_row = xor_stream(&plain_row, (seed & 0xFFFF) as u16); - plain_row[16..18].copy_from_slice(&(0x1C0_u16).to_le_bytes()); - let encrypted_row = xor_stream(&plain_row, (seed & 0xFFFF) as u16); - unknown_method[32..64].copy_from_slice(&encrypted_row); - - let path = write_temp_file("rsli-unknown-method", &unknown_method); - let lib = Library::open_path(&path).expect("open archive with unknown method failed"); - match lib.load(EntryId(0)) { - Err(Error::UnsupportedMethod { raw }) => assert_eq!(raw, 0x1C0), - other => panic!("expected UnsupportedMethod, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut bad_packed = valid.clone(); - bad_packed[32 + 28..32 + 32].copy_from_slice(&0xFFFF_FFF0_u32.to_le_bytes()); - let path = write_temp_file("rsli-bad-packed", &bad_packed); - match Library::open_path(&path) { - Err(Error::PackedSizePastEof { .. }) => {} - other => panic!("expected PackedSizePastEof, got {other:?}"), - } - let _ = fs::remove_file(&path); - - let mut with_bad_overlay = valid; - with_bad_overlay.extend_from_slice(b"AO"); - with_bad_overlay.extend_from_slice(&0xFFFF_FFFF_u32.to_le_bytes()); - let path = write_temp_file("rsli-bad-overlay", &with_bad_overlay); - match Library::open_path_with( - &path, - OpenOptions { - allow_ao_trailer: true, - allow_deflate_eof_plus_one: true, - }, - ) { - Err(Error::MediaOverlayOutOfBounds { .. }) => {} - other => panic!("expected MediaOverlayOutOfBounds, got {other:?}"), - } - let _ = fs::remove_file(&path); -} diff --git a/docs/specs/ai.md b/docs/specs/ai.md deleted file mode 100644 index 545c07b..0000000 --- a/docs/specs/ai.md +++ /dev/null @@ -1,5 +0,0 @@ -# AI system - -Документ описывает подсистему искусственного интеллекта: принятие решений, pathfinding и стратегическое поведение противников. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `ai.dll`. diff --git a/docs/specs/arealmap.md b/docs/specs/arealmap.md deleted file mode 100644 index cac2743..0000000 --- a/docs/specs/arealmap.md +++ /dev/null @@ -1,5 +0,0 @@ -# ArealMap - -Документ описывает формат и структуру карты мира: зоны/сектора, координаты, размещение объектов и связь с terrain и миссиями. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `ArealMap.dll`. diff --git a/docs/specs/behavior.md b/docs/specs/behavior.md deleted file mode 100644 index 9ffd2dc..0000000 --- a/docs/specs/behavior.md +++ /dev/null @@ -1,5 +0,0 @@ -# Behavior system - -Документ описывает поведенческую логику юнитов: state machine/behavior-паттерны, взаимодействия и базовые правила боевого поведения. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `Behavior.dll`. diff --git a/docs/specs/control.md b/docs/specs/control.md deleted file mode 100644 index a2d3d44..0000000 --- a/docs/specs/control.md +++ /dev/null @@ -1,5 +0,0 @@ -# Control system - -Документ описывает подсистему управления: mapping ввода (клавиатура, мышь, геймпад), обработку событий и буферизацию команд. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `Control.dll`. diff --git a/docs/specs/fxid.md b/docs/specs/fxid.md deleted file mode 100644 index 7dd1d4b..0000000 --- a/docs/specs/fxid.md +++ /dev/null @@ -1,834 +0,0 @@ -# FXID - -Документ фиксирует спецификацию ресурса эффекта `FXID` на уровне, достаточном для: - -- 1:1 загрузки и исполнения в совместимом runtime; -- построения валидатора payload; -- создания lossless-конвертера (`binary -> IR -> binary`); -- создания редактора с безопасным редактированием полей. - -Связанный контейнер: [NRes / RsLi](nres.md). - ---- - -## 1. Источники и статус восстановления - -Спецификация восстановлена по: - -- `tmp/disassembler1/Effect.dll.c`; -- `tmp/disassembler2/Effect.dll.asm`; -- интеграционным вызовам из `tmp/disassembler1/Terrain.dll.c`; -- проверке реальных архивов `testdata/nres`. - -Ключевые функции: - -- parser FXID: `Effect.dll!sub_10007650`; -- runtime loop: `sub_10003D30(case 28)`, `sub_10006170`, `sub_10008120`, `sub_10007D10`; -- alpha/time: `sub_10005C60`; -- exports: `CreateFxManager`, `InitializeSettings`. - -Проверка по данным: - -- `923/923` FXID payload валидны в `testdata/nres`. - ---- - -## 2. Контейнер и runtime API - -### 2.1. NRes entry - -FXID хранится как NRes-entry: - -- `type_id = 0x44495846` (`"FXID"`). - -Наблюдение по датасету (923 эффекта): - -- `attr1 = 0`, `attr2 = 0`, `attr3 = 1`. - -### 2.2. Export API `Effect.dll` - -Экспортируются: - -- `CreateFxManager(int a1, int a2, int owner)`; -- `InitializeSettings()`. - -`CreateFxManager` создаёт manager-объект (`0xB8` байт), инициализирует через `sub_10003AE0`, возвращает интерфейсный указатель (`base + 4`). - -### 2.3. Интерфейс менеджера - -Рабочая vtable (`off_1001E478`): - -| Смещение | Функция | Назначение | -|---|---|---| -| +0x08 | `sub_10003D30` | Event dispatcher (`4/20/23/24/28`) | -| +0x10 | `sub_10004320` | Открыть/закэшировать FX resource | -| +0x14 | `sub_10004590` | Создать runtime instance | -| +0x18 | `sub_10004780` | Удалить instance | -| +0x1C | `sub_100047B0` | Установить time/interp mode | -| +0x20 | `sub_100047D0` | Установить scale | -| +0x24 | `sub_10004830` | Установить позицию | -| +0x28 | `sub_10004930` | Установить matrix transform | -| +0x2C | `sub_10004B00` | Restart/retime | -| +0x38 | `sub_10004BA0` | Duration modifier | -| +0x3C | `sub_10004BD0` | Start/Enable | -| +0x40 | `sub_10004C10` | Stop/Disable | -| +0x44 | `sub_10004C50` | Bind emitter/context | -| +0x48 | `sub_10004D50` | Сброс frame flags | - -`Terrain.dll` использует `QueryInterface(id=19)` для получения рабочего интерфейса. - ---- - -## 3. Бинарный формат FXID payload - -Все значения little-endian. - -### 3.1. Header (60 байт, `0x3C`) - -```c -struct FxHeader60 { - uint32_t cmd_count; // 0x00 - uint32_t time_mode; // 0x04 - float duration_sec; // 0x08 - float phase_jitter; // 0x0C - uint32_t flags; // 0x10 - uint32_t settings_id; // 0x14 - float rand_shift_x; // 0x18 - float rand_shift_y; // 0x1C - float rand_shift_z; // 0x20 - float pivot_x; // 0x24 - float pivot_y; // 0x28 - float pivot_z; // 0x2C - float scale_x; // 0x30 - float scale_y; // 0x34 - float scale_z; // 0x38 -}; -``` - -Командный поток начинается строго с `offset = 0x3C`. - -### 3.2. Header-поля (подтвержденная семантика) - -- `cmd_count`: число команд (engine итерирует ровно столько шагов). -- `time_mode`: базовый режим вычисления alpha/time (`sub_10005C60`). -- `duration_sec`: в runtime -> `duration_ms = duration_sec * 1000`. -- `phase_jitter`: используется при `flags & 0x1`. -- `flags`: runtime-gating/alpha/visibility (см. ниже). -- `settings_id`: в `sub_1000EC40` используется `settings_id & 0xFF`. -- `rand_shift_*`: используется при `flags & 0x8`. -- `pivot_*`: используется в ветках `sub_10007D10`. -- `scale_*`: копируется в runtime scale и влияет на матрицы. - -### 3.3. `flags` (битовая карта) - -| Бит | Маска | Наблюдаемое поведение | -|---|---:|---| -| 0 | `0x0001` | Random phase jitter (`phase_jitter`) | -| 3 | `0x0008` | Random positional shift (`rand_shift_*`) | -| 4 | `0x0010` | Visibility/occlusion ветки | -| 5 | `0x0020` | Triangular remap в `sub_10005C60` | -| 6 | `0x0040` | Инверсия начального active-state | -| 7 | `0x0080` | Day/night filter (ветка A) | -| 8 | `0x0100` | Day/night filter (ветка B, инверсия) | -| 9 | `0x0200` | Alpha *= normalized lifetime | -| 10 | `0x0400` | Установка manager bit1 (`+0xA0`) | -| 11 | `0x0800` | Изменение gating в `sub_10007D10` | -| 12 | `0x1000` | Установка manager-state bit `0x10` | - -Нерасшифрованные биты должны сохраняться 1:1. - -### 3.4. `time_mode` (`0..17`) - -Обозначения (`sub_10005C60`): - -- `t0 = instance.start_ms`, `t1 = instance.end_ms`; -- `tn = (now_ms - t0) / (t1 - t0)`; -- `prev = instance.cached_alpha` (`v4+52` в дизассембле). - -Режимы: - -- `0`: constant (`instance.alpha_const`, поле `v4+40`); -- `1`: `tn`; -- `2`: `fract(tn)`; -- `3`: `1 - tn`; -- `4`: external value из queue/world API (manager `+36`, id из `this+104[a2]`); -- `5`: `|param33.xyz| / |param17.vecA.xyz|`; -- `6`: `param33.x / param17.vecA.x`; -- `7`: `param33.y / param17.vecA.y`; -- `8`: `param33.z / param17.vecA.z`; -- `9`: `|param36.xyz| / |param17.vecB.xyz|`; -- `10`: `param36.x / param17.vecB.x`; -- `11`: `param36.y / param17.vecB.y`; -- `12`: `param36.z / param17.vecB.z`; -- `13`: `1 - external_resource_value`; -- `14`: `1 - queue_param(49)`; -- `15`: `max(norm(param33/vecA), norm(param36/vecB))`; -- `16`: external (`mode 4`) с нижним clamp к `prev` (`0` не зажимается); -- `17`: external (`mode 4`) с верхним clamp к `prev` (`1` не зажимается). - -Post-обработка после mode: - -- если `flags & 0x200`: `alpha *= tn`; -- если `flags & 0x20`: triangular remap (`alpha = (alpha < 0.5 ? alpha : 1-alpha) * 2`). - ---- - -## 4. Командный поток - -### 4.1. Общий формат команды - -Каждая команда: - -- `uint32 cmd_word`; -- далее body фиксированного размера по opcode. - -`cmd_word`: - -- `opcode = cmd_word & 0xFF`; -- `enabled = (cmd_word >> 8) & 1`; -- `bits 9..31` в датасете нулевые, но их надо сохранять 1:1. - -Выравнивания между командами нет. - -### 4.2. Размеры - -| Opcode | Размер записи | -|---:|---:| -| 1 | 224 | -| 2 | 148 | -| 3 | 200 | -| 4 | 204 | -| 5 | 112 | -| 6 | 4 | -| 7 | 208 | -| 8 | 248 | -| 9 | 208 | -| 10 | 208 | - -### 4.3. Opcode -> runtime-класс (vtable) - -| Opcode | `new(size)` | vtable | -|---:|---:|---| -| 1 | `0xF0` | `off_1001E78C` | -| 2 | `0xA0` | `off_1001F048` | -| 3 | `0xFC` | `off_1001E770` | -| 4 | `0x104` | `off_1001E754` | -| 5 | `0x54` | `off_1001E360` | -| 6 | `0x1C` | `off_1001E738` | -| 7 | `0x48` | `off_1001E228` | -| 8 | `0xAC` | `off_1001E71C` | -| 9 | `0x100` | `off_1001E700` | -| 10 | `0x48` | `off_1001E24C` | - -### 4.4. Общий вызовной контракт команды - -После создания команды (`sub_10007650`): - -1. `cmd->enabled = cmd_word.bit8`. -2. `cmd->Init(fx_queue, fx_instance)` (`vfunc +4`). -3. команда добавляется в список инстанса. - -В runtime cycle: - -- `vfunc +8`: update/compute (bool); -- `vfunc +12`: emission/render callback; -- `vfunc +20`: toggle active; -- `vfunc +16`/`+24`: служебные функции (зависят от opcode). - ---- - -## 5. Загрузка FXID (engine-accurate) - -`sub_10007650`: - -```c -void FxLoad(FxInstance* fx, uint8_t* payload) { - FxHeader60* h = (FxHeader60*)payload; - - fx->raw_header = h; - fx->mode = h->time_mode; - fx->end_ms = fx->start_ms + h->duration_sec * 1000.0f; - fx->scale = {h->scale_x, h->scale_y, h->scale_z}; - fx->active_default = ((h->flags & 0x40) == 0); - - uint8_t* ptr = payload + 0x3C; - for (uint32_t i = 0; i < h->cmd_count; ++i) { - uint32_t w = *(uint32_t*)ptr; - uint8_t op = (uint8_t)(w & 0xFF); - - Command* cmd = CreateByOpcode(op, ptr); // может вернуть null - if (cmd) { - cmd->enabled = (w >> 8) & 1; - - if (h->flags & 0x400) fx->manager_flags |= 0x0100; - if ((h->flags & 0x400) || cmd->enabled) fx->manager_flags |= 0x0010; - - cmd->Init(fx->queue, fx); - fx->commands.push_back(cmd); - } - - ptr += size_by_opcode(op); // без bounds checks в оригинале - } -} -``` - -Критичные edge-case оригинала: - -- bounds checks отсутствуют; -- при unknown opcode `ptr` не двигается (`advance = 0`); -- при `new == null` команда пропускается, но `ptr` двигается. - -Фактический `advance` в `sub_10007650` задан hardcoded в DWORD: - -- `op1:+56`, `op2:+37`, `op3:+50`, `op4:+51`, `op5:+28`, -- `op6:+1`, `op7:+52`, `op8:+62`, `op9:+52`, `op10:+52`, -- `default:+0`. - ---- - -## 6. Runtime lifecycle - -- `sub_10007470`: ctor instance. -- `sub_10003D30(case 28)`: per-frame update manager. -- `sub_10006170`: gate + alpha/time + command updates. -- `sub_10008120` / `sub_10007D10`: update/render branches. -- Start/Stop: `sub_10004BD0` / `sub_10004C10`. - -Event-codes `sub_10003D30`: - -- `4`: bootstrap/time init; -- `20`: range-removal + index repair; -- `23`: set manager bit0; -- `24`: clear manager bit0; -- `28`: main tick. - ---- - -## 7. Общий тип `ResourceRef64` - -Для opcode `2/3/4/5/7/8/9/10` присутствует ссылка вида: - -```c -struct ResourceRef64 { - char archive[32]; // null-terminated ASCII, case-insensitive compare - char name[32]; // null-terminated ASCII -}; -``` - -Поведение loader'а: - -- оба имени обязаны быть непустыми; -- кэширование по `(_strcmpi archive, _strcmpi name)`; -- загрузка/резолв через manager resource API. - -Наблюдение по данным: - -- для `opcode 2`: обычно `sounds.lib` + `*.wav`; -- для остальных: обычно `material.lib` + material name. - ---- - -## 8. Полная карта body по opcode (field-level) - -Смещения указаны от начала команды (включая `cmd_word`). - -### 8.1. Opcode 1 (`off_1001E78C`, size=224) - -Основные методы: - -- init: `sub_1000F4B0`; -- update: `sub_1000F6E0`; -- emit: `nullsub_2`; -- toggle: `sub_1000F490`. - -```c -struct FxCmd01 { - uint32_t word; // +0 - uint32_t mode; // +4 (enum, см. ниже) - float t_start; // +8 - float t_end; // +12 - - float p0_min[3]; // +16..24 - float p0_max[3]; // +28..36 - - float p1_min[3]; // +40..48 - float p1_max[3]; // +52..60 - - float q0_min[4]; // +64..76 - float q0_max[4]; // +80..92 - - float q0_rand_span[4]; // +96..108 (все 4 читаются в sub_1000F6E0) - - float scalar_min; // +112 - float scalar_max; // +116 - float scalar_rand_amp; // +120 - - float color_rgb[3]; // +124..132 (вызов manager+16) - - float opaque_tail6[6]; // +136..156 (сохранять 1:1; в датасете почти всегда 0) - - char opt_archive[32]; // +160..191 (редко, напр. "material.lib") - char opt_name[32]; // +192..223 (редко, напр. "light_w") -}; -``` - -Замечания по полям op1: - -- `+108` не резерв: участвует в random-выборке как 4-я компонента блока `+96..108`; -- `+136..156` не читается vtable-методами класса `off_1001E78C` в `Effect.dll` (init/update/toggle/accessor), но должно сохраняться 1:1; -- редкий кейс с ненулевыми `+136..156` и строками `+160/+192` зафиксирован в `effects.rlb:r_lightray_w`. - -`mode` (`+4`) -> параметры вызова manager (`sub_1000F4B0`): - -- `1 -> create_kind=1, flags=0x80000000`; -- `2/5 -> create_kind=1, flags=0x00000000`; -- `3 -> create_kind=3, flags=0x00000000`; -- `4 -> create_kind=4, flags=0x00000000`; -- `6 -> create_kind=1, flags=0xA0000000`; -- `7 -> create_kind=1, flags=0x20000000`. - -### 8.2. Opcode 2 (`off_1001F048`, size=148) - -Основные методы: - -- init: `sub_10012D10`; -- update: `sub_10012EB0`; -- emit: `nullsub_2`; -- toggle: `sub_10013170`. - -```c -struct FxCmd02 { - uint32_t word; // +0 - uint32_t mode; // +4 (0..3; влияет на sub_100065A0 mapping) - float t_start; // +8 - float t_end; // +12 - - float a_min[3]; // +16..24 - float a_max[3]; // +28..36 - - float b_min[3]; // +40..48 - float b_max[3]; // +52..60 - - float c0_base; // +64 - float c1_base; // +68 - float c2_base; // +72 - float c2_max; // +76 - - uint32_t param_910; // +80 (передаётся в manager cmd=910) - - ResourceRef64 ref; // +84..147 (обычно sounds.lib + wav) -}; -``` - -`mode` -> внутренний map в `sub_100065A0`: - -- `0 -> 0`, `1 -> 512`, `2 -> 2`, `3 -> 514`. - -### 8.3. Opcode 3 (`off_1001E770`, size=200) - -Методы: - -- init: `sub_100103B0`; -- update: `sub_100105F0`; -- emit: `sub_100106C0`. - -```c -struct FxCmd03 { - uint32_t word; // +0 - uint32_t mode; // +4 - - float alpha_source; // +8 (>=0: norm time, <0: global time) - float alpha_pow_a; // +12 - float alpha_pow_b; // +16 - - float out_min; // +20 - float out_max; // +24 - float out_pow; // +28 - - float active_t0; // +32 - float active_t1; // +36 - - float v0_min[3]; // +40..48 - float v0_max[3]; // +52..60 - - float pow0[3]; // +64..72 - - float v1_min[3]; // +76..84 - float v1_max[3]; // +88..96 - - float v2_min[3]; // +100..108 - float v2_max[3]; // +112..120 - - float pow1[3]; // +124..132 - - ResourceRef64 ref; // +136..199 -}; -``` - -### 8.4. Opcode 4 (`off_1001E754`, size=204) - -Layout как opcode 3 + последний коэффициент: - -```c -struct FxCmd04 { - FxCmd03 base; // +0..199 - float dist_norm_inv_base; // +200 (используется в sub_100108C0/100109B0) -}; -``` - -`sub_100108C0`: `obj->inv = 1.0 / raw[200]`. - -### 8.5. Opcode 5 (`off_1001E360`, size=112) - -Методы: - -- init: `sub_100028A0`; -- update: `sub_10002A20`; -- emit: `sub_10002BE0`; -- context update: `sub_10003070`. - -```c -struct FxCmd05 { - uint32_t word; // +0 - uint32_t mode; // +4 (в данных обычно 1) - uint32_t unused_08; // +8 (в текущем коде opcode5 не читается) - uint32_t unused_0C; // +12 (в текущем коде opcode5 не читается) - - float active_t0; // +16 - uint32_t max_segments; // +20 - float active_t1_min; // +24 - float active_t1_max; // +28 - - float step_norm; // +32 - float segment_len; // +36 - float alpha_source; // +40 (>=0 norm, <0 random) - float alpha_pow; // +44 - - ResourceRef64 ref; // +48..111 -}; -``` - -### 8.6. Opcode 6 (`off_1001E738`, size=4) - -Только `cmd_word`: - -```c -struct FxCmd06 { - uint32_t word; // +0 -}; -``` - -`init/update/emit` фактически no-op (`sub_100030B0` возвращает `0`). - -### 8.7. Opcode 7 (`off_1001E228`, size=208) - -Методы: - -- init: `sub_10001720`; -- update: `sub_10001230`; -- emit: `sub_10001300`; -- element accessor: `sub_10002780`. - -```c -struct FxCmd07 { - uint32_t word; // +0 - uint32_t mode; // +4 - - float eval_min; // +8 - float eval_max; // +12 - float eval_pow; // +16 - - float active_t0; // +20 - float active_t1; // +24 - - float phase_span; // +28 - float phase_rate; // +32 - - uint32_t count_a; // +36 - uint32_t count_b; // +40 - - float set0_min[3]; // +44..52 - float set0_max[3]; // +56..64 - float set0_rand[3]; // +68..76 - float set0_pow[3]; // +80..88 - - float set1_min[3]; // +92..100 - float set1_max[3]; // +104..112 - float set1_rand[3]; // +116..124 - float set1_pow[3]; // +128..136 - - float gravity_or_drag_k; // +140 - - ResourceRef64 ref; // +144..207 -}; -``` - -### 8.8. Opcode 8 (`off_1001E71C`, size=248) - -Методы: - -- init: `sub_10011230`; -- update: `sub_100115C0`; -- emit: `sub_10012030`. - -```c -struct FxCmd08 { - uint32_t word; // +0 - uint32_t mode; // +4 - - float eval_t0; // +8 - float eval_t1; // +12 - - float gate_t0; // +16 - float gate_t1; // +20 - - float period_min; // +24 - float period_max; // +28 - float phase_pow; // +32 - - uint32_t slots; // +36 - - float set0_min[3]; // +40..48 - float set0_max[3]; // +52..60 - float set0_rand[3]; // +64..72 - - float set1_min[3]; // +76..84 - float set1_max[3]; // +88..96 - float set1_rand[3]; // +100..108 - - float set2_rand[3]; // +112..120 - float set2_pow[3]; // +124..132 - - float rmax_set0[3]; // +136..144 (bound/radius calc) - float rmax_set1[3]; // +148..156 (bound/radius calc) - float rmax_set2[3]; // +160..168 (bound/radius calc) - - float render_pow[3]; // +172..180 - - ResourceRef64 ref; // +184..247 -}; -``` - -### 8.9. Opcode 9 (`off_1001E700`, size=208) - -Layout как opcode 3 с двумя final-полями: - -```c -struct FxCmd09 { - FxCmd03 base; // +0..199 - uint32_t render_kind; // +200 (0/1/2 -> 3/5/6 in sub_100138C0) - uint32_t render_flag; // +204 (0 -> добавляет bit 0x08000000) -}; -``` - -Методы: - -- init/update как у opcode 3 (`sub_100103B0`, `sub_100105F0`); -- emit: `sub_100138C0` -> формирует код рендера и вызывает `sub_100106C0`. - -### 8.10. Opcode 10 (`off_1001E24C`, size=208) - -Body-layout совпадает с opcode 7 (`FxCmd07`), но другой runtime класс. - -- init: `sub_10001A40`; -- update: `sub_10001230`; -- emit: `sub_10001300`; -- element accessor: `sub_10002830`. - -Наблюдение по данным: - -- `mode` (`+4`) встречается как `16` или `32`. - ---- - -## 9. Runtime-специфика по opcode (важные отличия) - -### 9.1. Opcode 1 - -- создаёт handle через manager (`vfunc +48`); -- задаёт флаги handle (`vfunc +52`); -- в update пушит: - - позиционный вектор 1 (`vfunc +32`), - - позиционный вектор 2 (`vfunc +36`), - - 4-компонентный параметр (`vfunc +12`), - - scalar+rgb (`vfunc +16`). - -### 9.2. Opcode 2 - -- `ResourceRef64` резолвится через `sub_100065A0` (режим-зависимая загрузка, в данных обычно `sounds.lib`/`wav`); -- использует manager-команду id `910`. - -### 9.3. Opcode 3/4/9 - -- общий core-emitter в `sub_100106C0`; -- opcode 4 добавляет нормализацию по `raw+200`; -- opcode 9 добавляет переключение render-кода (`raw+200/+204`). - -### 9.4. Opcode 5 - -- держит массив внутренних сегментов (`332` байта/элемент, ctor `sub_100099F0`); -- context-matrix приходит через `vfunc +24` (`sub_10003070`). - -### 9.5. Opcode 7/10 - -- общий update/render (`sub_10001230`, `sub_10001300`); -- разные внутренние element-форматы: - - opcode 7: `204` байта/элемент (`sub_100092D0`), - - opcode 10: `492` байта/элемент (`sub_1000BB40`). - -### 9.6. Opcode 8 - -- самый тяжёлый спавнер, хранит ring/slot-структуры; -- emit фаза (`sub_10012030`) использует `mode`, `render_pow`, per-slot transforms. - ---- - -## 10. Спецификация инструментов - -### 10.1. Reader (strict) - -Алгоритм: - -1. `len(payload) >= 60`; -2. читаем `cmd_count`; -3. `ptr = 0x3C`; -4. цикл `cmd_count`: - - `ptr + 4 <= len`; - - `opcode in 1..10`; - - `ptr + size(opcode) <= len`; - - `ptr += size(opcode)`; -5. strict-tail: `ptr == len(payload)`. - -### 10.2. Reader (engine-compatible) - -Legacy-режим (опасный, только при необходимости byte-совместимости): - -- без bounds-check; -- tolerant к unknown opcode как в оригинале. - -### 10.3. Writer (canonical) - -1. записать `FxHeader60`; -2. `cmd_count = commands.len()`; -3. команды сериализуются как `cmd_word + fixed-body`; -4. размер payload: `0x3C + sum(size(op_i))`; -5. без хвостовых байт. - -### 10.4. Editor (lossless) - -Правила: - -- все поля little-endian; -- не менять fixed size команды; -- не добавлять padding; -- сохранять неизвестные биты (`cmd_word`, `header.flags`) copy-through; -- для частично-известных полей поддерживать режим `opaque`. - -### 10.5. IR/JSON (рекомендуемая форма) - -```json -{ - "header": { - "time_mode": 1, - "duration_sec": 2.5, - "phase_jitter": 0.2, - "flags": 22, - "settings_id": 785, - "rand_shift": [0.0, 0.0, 0.0], - "pivot": [0.0, 0.0, 0.0], - "scale": [1.0, 1.0, 1.0] - }, - "commands": [ - { - "opcode": 8, - "word_raw": 264, - "enabled": 1, - "fields": { - "mode": 1065353216, - "eval_t0": 0.0, - "eval_t1": 1.0, - "resource": {"archive": "material.lib", "name": "fire_smoke"} - }, - "opaque_extra_hex": "..." - } - ] -} -``` - ---- - -## 11. Проверка на реальных данных - -`testdata/nres`: - -- FXID payload: `923`; -- валидация parser'а: `923/923 valid`. - -Распределение opcode: - -- `1: 618` -- `2: 517` -- `3: 1545` -- `4: 202` -- `5: 31` -- `6: 0` (в датасете не встречен, но поддержан) -- `7: 1161` -- `8: 237` -- `9: 266` -- `10: 160` - -Подтверждённые `ResourceRef64` оффсеты: - -- op2 `+84`, op3/4/9 `+136`, op5 `+48`, op7/10 `+144`, op8 `+184`. - -Для op1 найден редкий расширенный хвост (`+160/+192`) в `effects.rlb:r_lightray_w`: - -- `material.lib` / `light_w`. - ---- - -## 12. Практический чек-лист 1:1 - -Для runtime-порта: - -- реализовать `FxHeader60` и parser `sub_10007650`; -- реализовать opcode-классы с методами как в vtable; -- учитывать start/stop/restart контракт manager API; -- воспроизвести `sub_10005C60` + post-flags (`0x20`, `0x200`); -- воспроизвести event loop `sub_10003D30(case 28)`. - -Для toolchain: - -- strict validator по разделу 10.1; -- canonical writer по разделу 10.3; -- field-aware editor + opaque fallback для неизвестных зон. - ---- - -## 13. Что считать «полной» совместимостью - -Практический критерий завершения: - -1. Парсер и writer дают byte-identical round-trip для всех 923 FXID. -2. Runtime-порт выдаёт совпадающие state transitions на одинаковом `dt/seed` (по ключевым полям instance + command state). -3. Все opcode `1..10` поддержаны (включая `6`, даже если отсутствует в текущем датасете). -4. `ResourceRef64` и mode-ветки (`op1`, `op2`, `op9`) совпадают с оригиналом. - -Эта страница покрывает весь наблюдаемый контракт формата/рантайма и полную карту body-полей по всем opcode. - ---- - -## 14. Что осталось до «абсолютных 100%» - -Для практического 1:1 (парсер/writer/runtime на известном контенте) покрытие уже достаточно. -Для «абсолютных 100%» на любых входах и во всех краевых режимах остаются 3 пункта: - -1. FP-детерминизм: оригинал опирается на x87-style вычисления; SSE/fast-math могут давать расхождения в alpha/таймингах. -2. RNG parity: используется `sub_10002220` (16-bit генератор) и глобальные seed-состояния; для bit-exact воспроизведения нужны контрольные трассы оригинала. -3. Редкие ветки данных: в текущем датасете нет opcode `6`, и почти не встречаются хвосты op1 (`+136..223`); для исчерпывающей валидации нужны дополнительные FXID-образцы. - -Что нужно собрать, чтобы закрыть это полностью: - -- frame-by-frame dump из оригинального runtime (alpha, manager flags, per-command state); -- контрольные прогоны при фиксированном `dt` и seed; -- минимум по одному ресурсу на каждую редкую ветку (`op6`, op1-tail с ненулевыми `+136..223`). diff --git a/docs/specs/materials-texm.md b/docs/specs/materials-texm.md deleted file mode 100644 index baa80ae..0000000 --- a/docs/specs/materials-texm.md +++ /dev/null @@ -1,874 +0,0 @@ -# Materials, WEAR, MAT0 и Texm - -Документ описывает материальную подсистему движка (World3D/Ngi32) на уровне, достаточном для: - -- реализации runtime 1:1; -- создания инструментов чтения/валидации; -- создания инструментов конвертации и редактирования с lossless round-trip. - -Источник: дизассемблированные `tmp/disassembler1/*.c` и `tmp/disassembler2/*.asm`, плюс проверка на `tmp/gamedata`. - ---- - -## 1. Идентификаторы и сущности - -| Сущность | ID (LE uint32) | ASCII | Где используется | -|---|---:|---|---| -| Material resource | `0x3054414D` | `MAT0` | `Material.lib` | -| Wear resource | `0x52414557` | `WEAR` | `.wea` записи в world/mission `.rlb` | -| Texture resource | `0x6D786554` | `Texm` | `Textures.lib`, `lightmap.lib`, другие `.lib/.rlb` | -| Atlas tail chunk | `0x65676150` | `Page` | хвост payload `Texm` | - -Дополнительно: палитры загружаются отдельным путём (через `SetPalettesLib` + `sub_10002B40`) и не являются `Texm`. - ---- - -## 2. Архитектура подсистемы - -### 2.1 Экспортируемые точки входа (World3D) - -- `LoadMatManager` -- `SetPalettesLib` -- `SetTexturesLib` -- `SetMaterialLib` -- `SetLightMapLib` -- `SetGameTime` -- `UnloadAllTextures` - -`Set*Lib` просто копируют строки путей в глобальные буферы; валидации пути нет. - -### 2.2 Дефолтные библиотеки (из `iron3d.dll`) - -- `Textures.lib` -- `Material.lib` -- `LightMap.lib` -- `palettes.lib` (строка собирается как `'p' + "alettes.lib"`) - -### 2.3 Ключевые runtime-хранилища - -1. Менеджер материалов (`LoadMatManager`) — объект `0x470` байт. -2. Кэш текстурных объектов. -3. Кэш lightmap-объектов. -4. Банк загруженных палитр. -5. Глобальный пул определений материалов (`MAT0`). - ---- - -## 3. Layout `MatManager` (0x470) - -Объект содержит 70 таблиц wear/lightmaps (не 140). - -```c -// int-индексы относительно this (DWORD*), размер 284 DWORD = 0x470 -// [0] vtable -// [1] callback iface -// [2] callback data -// [3..72] wearTablePtrs[70] // ptr на массив по 8 байт -// [73..142] wearCounts[70] -// [143] tableCount -// [144..213] lightmapTablePtrs[70] // ptr на массив по 4 байта -// [214..283] lightmapCounts[70] -``` - -### 3.1 Vtable методов (`off_100209E4`) - -| Индекс | Функция | Назначение | -|---:|---|---| -| 0 | `loc_10002CE0` | служебный/RTTI-заглушка | -| 1 | `sub_10002D10` | деструктор + освобождение таблиц | -| 2 | `PreLoadAllTextures` | экспорт, но фактически `retn 4` (заглушка) | -| 3 | `sub_100031F0` | получить материал-фазу по `gameTime` | -| 4 | `sub_10003AE0` | сбросить startTime записи wear к `SetGameTime()` | -| 5 | `sub_10003680` | получить материал-фазу по нормализованному `t` | -| 6 | `sub_10003B10` | загрузить wear/lightmaps (файл/ресурс) | -| 7 | `sub_10003F80` | загрузить wear/lightmaps из буфера | -| 8 | `sub_100031A0` | получить указатель на lightmap texture object | -| 9 | `sub_10003AB0` | получить runtime-метаданные материала | -| 10 | `sub_100031D0` | получить `wearCount` для таблицы | - -### 3.2 Кодирование material-handle - -`uint32 handle = (tableIndex << 16) | wearIndex`. - -- `HIWORD(handle)` -> индекс таблицы `0..69` -- `LOWORD(handle)` -> индекс материала в wear-таблице - ---- - -## 4. Глобальные кэши и их ёмкость - -Ёмкости подтверждены границами циклов/адресов в дизассемблере. - -### 4.1 Кэш текстур (`dword_1014E910`...) - -- Размер слота: `5 DWORD` (20 байт) -- Ёмкость: `777` - -```c -struct TextureSlot { - int32_t resIndex; // +0 индекс записи в NRes (не hash), -1 = свободно - void* textureObject; // +4 - int32_t refCount; // +8 - uint32_t lastZeroRefTime;// +12 время, когда refCount стал 0 - uint32_t loadFlags; // +16 флаги загрузки -}; -``` - -`lastZeroRefTime` реально используется: texture-слоты с `refCount==0` освобождаются отложенно периодическим GC. - -### 4.2 Кэш lightmaps (`dword_10029C98`...) - -- Тот же layout `5 DWORD` -- Ёмкость: `100` - -Для lightmap-слотов аналогичного периодического GC по `lastZeroRefTime` в `World3D` не наблюдается. - -### 4.3 Пул материалов (`dword_100669F0`...) - -- Шаг: `92 DWORD` (`368` байт) -- Ёмкость: `700` - -Фиксированные поля на шаг `i*92`: - -| DWORD offset | Byte offset | Поле | -|---:|---:|---| -| 0 | 0 | `nameResIndex` (`MAT0` entry index), `-1` = free | -| 1 | 4 | `refCount` | -| 2 | 8 | `phaseCount` | -| 3 | 12 | `phaseArrayPtr` (`phaseCount * 76`) | -| 4 | 16 | `animBlockCount` (`< 20`) | -| 5..84 | 20..339 | `animBlocks[20]` по 16 байт | -| 85 | 340 | metaA (`dword_10066B44`) | -| 86 | 344 | metaB (`dword_10066B48`) | -| 87 | 348 | metaC (`dword_10066B4C`) | -| 88 | 352 | metaD (`dword_10066B50`) | -| 89 | 356 | flagA (`dword_10066B54`) | -| 90 | 360 | nibbleMode (`dword_10066B58`) | -| 91 | 364 | flagB (`dword_10066B5C`) | - -### 4.4 Банк палитр - -- `dword_1013DA58[]` -- Загружается до `286` элементов (26 букв * 11 вариантов) - ---- - -## 5. Загрузка палитр (`sub_10002B40`) - -### 5.1 Генерация имён - -Движок перебирает: - -- буквы `'A'..'Z'` -- суффиксы: `""`, `"0"`, `"1"`, ..., `"9"` - -И формирует имя: - -- `<Letter><Suffix>.PAL` -- примеры: `A.PAL`, `A0.PAL`, ..., `Z9.PAL` - -### 5.2 Индекс палитры - -`paletteIndex = letterIndex * 11 + variantIndex` - -- `letterIndex = 0..25` -- `variantIndex = 0..10` (`""`=0, `"0"`=1, ..., `"9"`=10) - -### 5.3 Поведение - -- Если запись не найдена: `paletteSlots[idx] = 0` -- Если найдена: payload отдаётся в рендер (`render->method+60`) - ---- - -## 6. Формат `MAT0` (`Material.lib`) - -### 6.1 Атрибуты NRes entry - -`sub_10004310` использует: - -- `entry.type` = `MAT0` -- `entry.attr1` (bitfield runtime-флагов) -- `entry.attr2` (версия/вариант заголовка payload) -- `entry.attr3` не используется в runtime-парсере - -Маппинг `attr1`: - -- bit0 (`0x01`) -> добавить флаг `0x200000` в загрузку текстур фазы -- bit1 (`0x02`) -> `flagA=1`; при некоторых HW-условиях дополнительно OR `0x80000` -- bits2..5 -> `nibbleMode = (attr1 >> 2) & 0xF` -- bit6 (`0x40`) -> `flagB=1` - -### 6.2 Payload layout - -```c -struct Mat0Payload { - uint16_t phaseCount; - uint16_t animBlockCount; // должно быть < 20, иначе "Too many animations for material." - - // Если attr2 >= 2: - uint8_t metaA8; - uint8_t metaB8; - // Если attr2 >= 3: - uint32_t metaC32; - // Если attr2 >= 4: - uint32_t metaD32; - - PhaseRecordByte34 phases[phaseCount]; - AnimBlockRaw anim[animBlockCount]; -}; -``` - -Если `attr2 < 2`, runtime-значения по умолчанию: - -- `metaA = 255` -- `metaB = 255` -- `metaC = 1.0f` (`0x3F800000`) -- `metaD = 0` - -### 6.3 `PhaseRecordByte34` -> runtime `76 bytes` - -Сырые 34 байта: - -```c -struct PhaseRecordByte34 { - uint8_t p[18]; // параметры - char textureName[16];// если textureName[0]==0, текстуры нет -}; -``` - -Преобразование в runtime-структуру (точный порядок): - -| Из `p[i]` | В offset runtime | Преобразование | -|---:|---:|---| -| `p[0]` | `+16` | `p[0] / 255.0f` | -| `p[1]` | `+20` | `p[1] / 255.0f` | -| `p[2]` | `+24` | `p[2] / 255.0f` | -| `p[3]` | `+28` | `p[3] * 0.01f` | -| `p[4]` | `+0` | `p[4] / 255.0f` | -| `p[5]` | `+4` | `p[5] / 255.0f` | -| `p[6]` | `+8` | `p[6] / 255.0f` | -| `p[7]` | `+12` | `p[7] / 255.0f` | -| `p[8]` | `+32` | `p[8] / 255.0f` | -| `p[9]` | `+36` | `p[9] / 255.0f` | -| `p[10]` | `+40` | `p[10] / 255.0f` | -| `p[11]` | `+44` | `p[11] / 255.0f` | -| `p[12]` | `+48` | `p[12] / 255.0f` | -| `p[13]` | `+52` | `p[13] / 255.0f` | -| `p[14]` | `+56` | `p[14] / 255.0f` | -| `p[15]` | `+60` | `p[15] / 255.0f` | -| `p[16]` | `+64` | `uint32 = p[16]` | -| `p[17]` | `+72` | `int32 = p[17]` | - -Текстура: - -- `textureName[0] == 0` -> `runtime[+68] = -1` и `runtime[+72] = -1` -- иначе `runtime[+68] = LoadTexture(textureName, flags)` - -### 6.4 Runtime-запись фазы (76 байт) - -```c -struct MaterialPhase76 { - float f0; // +0 - float f1; // +4 - float f2; // +8 - float f3; // +12 - float f4; // +16 - float f5; // +20 - float f6; // +24 - float f7; // +28 - float f8; // +32 - float f9; // +36 - float f10; // +40 - float f11; // +44 - float f12; // +48 - float f13; // +52 - float f14; // +56 - float f15; // +60 - uint32_t u16; // +64 - int32_t texSlot; // +68 (индекс в texture cache, либо -1) - int32_t i18; // +72 -}; -``` - -### 6.5 Анимационные блоки (`animBlockCount`, максимум 19) - -Каждый блок в payload: - -```c -struct AnimBlockRaw { - uint32_t headerRaw; // mode = headerRaw & 7; interpMask = headerRaw >> 3 - uint16_t keyCount; - struct KeyRaw { - uint16_t k0; - uint16_t k1; - uint16_t k2; - } keys[keyCount]; -}; -``` - -Runtime-представление блока = 16 байт: - -```c -struct AnimBlockRuntime { - uint32_t mode; // headerRaw & 7 - uint32_t interpMask;// headerRaw >> 3 - int32_t keyCount; - void* keysPtr; // массив keyCount * 8 -}; -``` - -Ключи в runtime занимают 8 байт/ключ (с расширением `k0` до `uint32`). - -`k2` в `sub_100031F0/sub_10003680` не используется. -Поле нужно сохранять lossless, т.к. оно присутствует в бинарном формате. - -### 6.6 Поиск и fallback - -При `LoadMaterial(name)`: - -- сначала точный поиск в `Material.lib`; -- при промахе лог: `"Material %s not found."`; -- fallback на `DEFAULT`; -- если и `DEFAULT` не найден, берётся индекс `0`. - ---- - -## 7. Выбор текущей material-фазы - -### 7.1 Интерполяция (`sub_10003030`) - -Интерполируются только следующие поля (по `interpMask`): - -- bit `0x02`: `+4,+8,+12` -- bit `0x01`: `+20,+24,+28` -- bit `0x04`: `+36,+40,+44` -- bit `0x08`: `+52,+56,+60` -- bit `0x10`: `+32` - -Не интерполируются и копируются из «текущей» фазы: - -- `+0,+16,+48,+64,+68,+72` - -### 7.2 Выбор по времени (`sub_100031F0`) - -Вход: - -- `handle` (`tableIndex|wearIndex`) -- `animBlockIndex` -- глобальное время `SetGameTime()` (`dword_10032A38`) - -Для каждой wear-записи хранится `startTime` (второй DWORD пары `8-byte`). - -Режимы `mode = headerRaw & 7`: - -- `0`: loop -- `1`: ping-pong -- `2`: one-shot clamp -- `3`: random (`rand() % cycleLength`) - -Важные детали 1:1: - -- деление/остаток по циклу реализованы через unsigned `div` (`edx=0` перед делением); -- в `mode=3` вычисленное `rand() % cycleLength` записывается прямо в `startTime` записи (не в локальную переменную). -- при `gameTime < startTime` применяется unsigned-wrap семантика (важно для точного воспроизведения edge-case). - -После выбора сегмента интерполяции `sub_10003030` строит scratch-материал (`unk_1013B300`), который возвращается через out-параметр. - -### 7.3 Выбор по нормализованному `t` (`sub_10003680`) - -Аналогично `sub_100031F0`, но time берётся как `t * cycleLength`. - -Перед вычислением времени применяется runtime-нормализация: - -- если `t < 0.0` или `t > 1.0`, используется `t = 0.5`. - -### 7.4 Сброс времени записи - -`sub_10003AE0` обновляет `startTime` конкретной wear-записи значением текущего `SetGameTime()`. - ---- - -## 8. Формат `WEAR` (текст) - -`WEAR` хранится как текст в NRes entry типа `WEAR` (`0x52414557`), обычно имя `*.wea`. - -### 8.1 Грамматика - -```text -<wearCount:int>\n -<legacyId:int> <materialName>\n // повторить wearCount раз - -[\n] // для buffer-парсера с LIGHTMAPS фактически обязательна пустая строка -[LIGHTMAPS\n -<lightmapCount:int>\n -<legacyId:int> <lightmapName>\n // повторить lightmapCount раз] -``` - -- `<legacyId>` читается, но как ключ не используется. -- Идентификатором реально является имя (`materialName` / `lightmapName`). - -### 8.2 Парсеры - -1. `sub_10003B10`: файл/ресурсный режим. -2. `sub_10003F80`: парсер из строкового буфера. - -Различие важно для совместимости: - -- `sub_10003B10` после `LIGHTMAPS` сразу читает `lightmapCount` через `fscanf`. -- `sub_10003F80` после детекта `LIGHTMAPS` делает два последовательных skip до `\n`; поэтому при наличии блока `LIGHTMAPS` нужен пустой разделитель перед строкой `LIGHTMAPS`, иначе парсинг может съехать. - -### 8.3 Поведение и ошибки - -- `wearCount <= 0` (в текстовом файловом режиме) -> `"Illegal wear length."` -- при невозможности открыть wear-файл/entry -> `"Wear <%s> doesn't exist."` -- если найден блок `LIGHTMAPS` и `lightmapCount <= 0` -> `"Illegal lightmaps length."` -- отсутствующий материал -> `"Material %s not found."` + fallback `DEFAULT` -- отсутствующая lightmap -> `"LightMap %s not found."` и slot `-1` -- в buffer-режиме неверная структура вокруг `LIGHTMAPS` может дать некорректный `lightmapCount` и каскадные ошибки чтения. - -### 8.4 Ограничения runtime - -- Таблиц в `MatManager`: максимум 70 (физический layout). -- Жёсткой проверки на overflow таблиц в `sub_10003B10/sub_10003F80` нет. - -Инструментам нужно явно валидировать `tableCount < 70`. - ---- - -## 9. Загрузка texture/lightmap по имени - -Общие функции: - -- `sub_10004B10` — texture (`Textures.lib`) -- `sub_10004CB0` — lightmap (`LightMap.lib`) - -### 9.1 Валидация имени - -Алгоритм требует наличие `'.'` в позиции `0..16`. - -Иначе: - -- `"Bad texture name."` -- возврат `-1` - -### 9.2 Palette index из суффикса - -После точки разбирается: - -- `L = toupper(name[dot+1])` -- `D = name[dot+2]` (опционально) -- `idx = (L - 'A') * 11 + (D ? (D - '0' + 1) : 0)` - -Если `idx < 0`, палитра не подставляется (`0`). -Верхняя граница `idx` в runtime не проверяется. - -Практически в стоковых ассетах имена часто вида `NAME.0`; это даёт `idx < 0`, т.е. без палитровой привязки. -Для невалидных суффиксов это потенциально даёт OOB-чтение палитрового массива. - -### 9.3 Кэширование - -- Дедупликация по `resIndex`. -- При повторном запросе увеличивается `refCount`, `lastZeroRefTime` сбрасывается в `0`. -- При освобождении материала `refCount` texture/lightmap уменьшается. -- texture: при `refCount -> 0` запоминается `lastZeroRefTime`; периодический sweep (примерно раз в 20 секунд) удаляет слот, если прошло больше `~60` секунд. -- lightmap: явного аналогичного sweep-пути нет; освобождение в основном происходит при teardown таблиц (`MatManager` dtor). - ---- - -## 10. Формат `Texm` - -### 10.1 Заголовок 32 байта - -```c -struct TexmHeader32 { - uint32_t magic; // 'Texm' = 0x6D786554 - uint32_t width; - uint32_t height; - uint32_t mipCount; - uint32_t flags4; - uint32_t flags5; - uint32_t unk6; - uint32_t format; -}; -``` - -### 10.2 Поддерживаемые `format` - -Подтверждённые в данных: - -- `0` (палитровый 8-bit) -- `565` -- `4444` -- `888` -- `8888` - -Поддерживается loader-ветками Ngi32 (может встречаться в runtime-генерации): - -- `556` -- `88` - -### 10.3 Layout payload - -1. `TexmHeader32` -2. если `format == 0`: palette table `256 * 4 = 1024` байта -3. mip-chain пикселей -4. опциональный `Page` chunk - -Расчёт: - -```c -bytesPerPixel = - (format == 0) ? 1 : - (format == 565 || format == 556 || format == 4444 || format == 88) ? 2 : - 4; - -pixelCount = sum_{i=0..mipCount-1}(max(1, width>>i) * max(1, height>>i)); -sizeCore = 32 + (format == 0 ? 1024 : 0) + bytesPerPixel * pixelCount; -``` - -### 10.4 `Page` chunk - -```c -struct PageChunk { - uint32_t magic; // 'Page' - uint32_t rectCount; - struct Rect16 { - int16_t x; - int16_t w; - int16_t y; - int16_t h; - } rects[rectCount]; -}; -``` - -Runtime конвертирует `Rect16` в: - -- пиксельные прямоугольники; -- UV-границы с учётом возможного `mipSkip`. - -Формулы (`s = mipSkip`): - -- `x0 = x << s`, `x1 = (x + w) << s` -- `y0 = y << s`, `y1 = (y + h) << s` -- `u0 = x / (width << s)`, `du = w / (width << s)` -- `v0 = y / (height << s)`, `dv = h / (height << s)` - -Также всегда добавляется базовый rect `[0]` на всю текстуру: пиксели `(0,0,width,height)`, UV `(0,0,1,1)`. - -### 10.5 Loader-поведение (`sub_1000FB30`) - -- Читает header в внутренние поля (`+56..+84`) напрямую: - - `+56 magic`, `+60 width`, `+64 height`, `+68 mipCount`, - - `+72 flags4`, `+76 flags5`, `+80 unk6`, `+84 format`. -- Для `format==0` считывает palette и переставляет каналы в runtime-таблицу. -- Считает `sizeCore`, находит tail. -- `Page` разбирается только если включён флаг загрузки `0x400000` и tail содержит `Page`. -- Может уменьшать стартовый mip (`sub_1000F580`) в зависимости от размеров/формата/флагов. -- При `DisableMipmap == 0` и допустимых условиях может строить mips в runtime. - -### 10.6 Политика `mipSkip` (`sub_1000F580`) - -`mipSkip` зависит от `flags5 & 0x72000000`, `width`, `height`, `mipCount`: - -- если `mipCount <= 1` -> `0` -- если `flags5Mask == 0x02000000` -> `2` при `mipCount > 2`, иначе `1` -- если `flags5Mask == 0x10000000` -> `1` -- если `flags5Mask == 0x20000000`: - - `1`, если `width >= 256` или `height >= 256` - - иначе `0` -- если `flags5Mask == 0x40000000`: - - если `width > 128` и `height > 128`: `2` при `mipCount > 2`, иначе `1` - - если `width == 128` или `height == 128`: `1` - - иначе `0` -- иначе `0` - -Применение в loader: - -- `mipCount -= mipSkip` -- `width >>= mipSkip`, `height >>= mipSkip` -- `pixelDataOffset += bytesPerPixel * origWidth * origHeight` для `mipSkip==1` -- `pixelDataOffset += bytesPerPixel * origWidth * origHeight * 1.25` для `mipSkip==2` (первые два уровня) - ---- - -## 11. Флаги профиля/рендера (Ngi32) - -Ключ реестра: `HKCU\Software\Nikita\NgiTool`. - -Подтверждённые значения: - -- `Disable MultiTexturing` -- `DisableMipmap` -- `Force 16-bit textures` -- `UseFirstCard` -- `DisableD3DCalls` -- `DisableDSound` -- `ForceCpu` - -Они напрямую влияют на выбор texture format path, mip handling и fallback-ветки. - ---- - -## 12. Спецификация для toolchain (read/edit/write) - -### 12.1 Каноническая модель данных - -1. `MAT0`: -- хранить исходные `attr1/attr2/attr3`; -- хранить сырой payload + декодированную структуру; -- при записи сохранять порядок/размеры секций точно. - -2. `WEAR`: -- хранить строки wear/lightmaps как текст; -- сохранять порядок строк; -- допускать отсутствие блока `LIGHTMAPS`. -- если нужен полный runtime-parity с buffer-парсером (`sub_10003F80`) и есть `LIGHTMAPS`, сохранять пустую строку-разделитель перед строкой `LIGHTMAPS`. - -3. `Texm`: -- хранить header поля как есть (`flags4/flags5/unk6` не нормализовать); -- хранить palette (если есть), mip data, `Page`. - -### 12.2 Правила lossless записи - -- Не менять значения `flags4/flags5/unk6` без явной причины. -- Не менять `NRes` entry attrs, если цель — бинарный round-trip. -- Для `MAT0`: - - `animBlockCount < 20`. - - `phaseCount` и фактический размер секции должны совпадать. - - textureName в фазе всегда укладывать в 16 байт и NUL-терминировать. -- Для `Texm`: - - `magic == 'Texm'`. - - `mipCount > 0`, `width>0`, `height>0`. - - tail либо отсутствует, либо ровно один корректный `Page` chunk без лишних байт. - - при эмуляции runtime-загрузчика учитывать, что `Page` обрабатывается только при load-flag `0x400000`. - -### 12.3 Рекомендованные валидации редактора - -- `WEAR`: - - `wearCount > 0`. - - число строк wear соответствует `wearCount`. - - если есть `LIGHTMAPS`, то `lightmapCount > 0` и число строк совпадает. - - для buffer-совместимого текста с `LIGHTMAPS` проверять наличие пустой строки перед `LIGHTMAPS`. -- `MAT0`: - - не выходить за payload при распаковке. - - все ссылки фаз/keys проверять на диапазоны. -- `Texm`: - - `sizeCore <= payload_size`. - - проверка `Page` как `8 + rectCount*8`. - - предупреждать/блокировать невалидные palette suffix, которые могут дать `idx >= 286` в runtime. - ---- - -## 13. Проверка на реальных данных (`tmp/gamedata`) - -### 13.1 `Material.lib` - -- `905` entries, все `type=MAT0` -- `attr2 = 6` у всех -- `attr3 = 0` у всех -- `phaseCount` до `29` -- `animBlockCount` до `8` (ограничение runtime `<20` соблюдается) - -### 13.2 `Textures.lib` - -- `393` entries, все `type=Texm` -- форматы: `8888(237), 888(52), 565(47), 4444(42), 0(15)` -- `flags4`: `32(361), 0(32)` -- `flags5`: `0(312), 0x04000000(81)` -- `Page` chunk присутствует у `65` текстур - -### 13.3 `lightmap.lib` - -- `25` entries, все `Texm` -- формат: `565` -- `mipCount=1` -- `flags5`: в основном `0`, встречается `0x00800000` - -### 13.4 `WEAR` - -- `439` entries `type=WEAR` -- `attr1=0, attr2=0, attr3=1` -- `21` entry содержит блок `LIGHTMAPS` (в текущем наборе везде `lightmapCount=1`) -- для всех `21` entry с `LIGHTMAPS` присутствует пустая строка перед `LIGHTMAPS`. - ---- - -## 14. Opaque-поля и границы знания - -Для 1:1 runtime/toolchain достаточно фиксировать следующие поля как `opaque-but-required`: - -- `MAT0`: - - `k2` в `AnimBlockRaw::KeyRaw` (хранить/писать без изменений); - - `metaA/metaB/metaC/metaD` (в `World3D` заполняются и возвращаются наружу; внутренних consumers этих мета-полей не найдено). -- `Texm`: - - `flags4/flags5/unk6` (часть веток разобрана, но полная доменная семантика не требуется для 1:1). - -Это не блокирует реализацию движка/конвертеров 1:1. - ---- - -## 15. Минимальные псевдокоды для реализации - -### 15.1 `parse_mat0(payload, attr2)` - -```python -def parse_mat0(payload: bytes, attr2: int): - cur = 0 - phase_count = u16(payload, cur); cur += 2 - anim_count = u16(payload, cur); cur += 2 - if anim_count >= 20: - raise ValueError("Too many animations for material") - - if attr2 < 2: - metaA, metaB, metaC, metaD = 255, 255, 0x3F800000, 0 - else: - metaA = u8(payload, cur); cur += 1 - metaB = u8(payload, cur); cur += 1 - metaC = u32(payload, cur) if attr2 >= 3 else 0x3F800000 - cur += 4 if attr2 >= 3 else 0 - metaD = u32(payload, cur) if attr2 >= 4 else 0 - cur += 4 if attr2 >= 4 else 0 - - phases = [payload[cur + i*34 : cur + (i+1)*34] for i in range(phase_count)] - cur += 34 * phase_count - - anim = [] - for _ in range(anim_count): - raw = u32(payload, cur); cur += 4 - key_count = u16(payload, cur); cur += 2 - keys = [payload[cur + k*6 : cur + (k+1)*6] for k in range(key_count)] - cur += 6 * key_count - anim.append((raw, keys)) - - if cur != len(payload): - raise ValueError("MAT0 tail bytes") - - return phase_count, anim_count, metaA, metaB, metaC, metaD, phases, anim -``` - -### 15.2 `parse_texm(payload)` - -```python -def parse_texm(payload: bytes): - magic, w, h, mips, f4, f5, unk6, fmt = unpack_u32x8(payload, 0) - if magic != 0x6D786554: - raise ValueError("not Texm") - - bpp = 1 if fmt == 0 else (2 if fmt in (565, 556, 4444, 88) else 4) - pix = 0 - mw, mh = w, h - for _ in range(mips): - pix += mw * mh - mw = max(1, mw >> 1) - mh = max(1, mh >> 1) - - core = 32 + (1024 if fmt == 0 else 0) + bpp * pix - if core > len(payload): - raise ValueError("truncated") - - page = None - if core < len(payload): - if core + 8 > len(payload) or payload[core:core+4] != b"Page": - raise ValueError("tail without Page") - n = u32(payload, core + 4) - need = 8 + n * 8 - if core + need != len(payload): - raise ValueError("invalid Page size") - page = [unpack_i16x4(payload, core + 8 + i*8) for i in range(n)] - - return (w, h, mips, fmt, f4, f5, unk6, page) -``` - -### 15.3 `mip_skip_policy(flags5, width, height, mip_count)` - -```python -def mip_skip_policy(flags5: int, width: int, height: int, mip_count: int) -> int: - if mip_count <= 1: - return 0 - - m = flags5 & 0x72000000 - if m == 0x02000000: - return 2 if mip_count > 2 else 1 - if m == 0x10000000: - return 1 - if m == 0x20000000: - return 1 if (width >= 256 or height >= 256) else 0 - if m == 0x40000000: - if width > 128 and height > 128: - return 2 if mip_count > 2 else 1 - if width == 128 or height == 128: - return 1 - return 0 -``` - -### 15.4 `parse_wear_buffer_compatible(text)` - -```python -def parse_wear_buffer_compatible(text: str): - lines = text.splitlines() - i = 0 - - wear_count = int(lines[i].strip()); i += 1 - if wear_count <= 0: - raise ValueError("Illegal wear length.") - - wear = [] - for _ in range(wear_count): - legacy, name = lines[i].split(maxsplit=1) - wear.append((int(legacy), name.strip())) - i += 1 - - lightmaps = [] - tail = lines[i:] if i < len(lines) else [] - if tail and tail[0].strip() == "": - # sub_10003F80-совместимый разделитель перед LIGHTMAPS - i += 1 - tail = lines[i:] - - if tail and tail[0].strip().upper() == "LIGHTMAPS": - i += 1 - if i >= len(lines): - raise ValueError("Illegal lightmaps length.") - light_count = int(lines[i].strip()); i += 1 - if light_count <= 0: - raise ValueError("Illegal lightmaps length.") - for _ in range(light_count): - legacy, name = lines[i].split(maxsplit=1) - lightmaps.append((int(legacy), name.strip())) - i += 1 - - return wear, lightmaps -``` - -### 15.5 `select_phase_time_1to1(...)` - -```python -def select_phase_time_1to1(game_time: int, start_time: int, keys, mode: int): - # keys: list[(phase_index, t_start, t_end)], t_end последнего = cycle_len - cycle_len = keys[-1][2] - if cycle_len <= 0: - return 0, 0.0 - - # unsigned div/mod как в runtime - delta = (game_time - start_time) & 0xFFFFFFFF - q = delta // cycle_len - r = delta % cycle_len - - if mode == 1: # ping-pong - if q & 1: - r = cycle_len - r - elif mode == 2: # one-shot - if q > 0: - k = len(keys) - 1 - return k, 0.0 - elif mode == 3: # random - r = rand32() % cycle_len - start_time = r # side effect как в sub_100031F0 - - k = find_segment(keys, r) # t_start <= r < t_end - kn = 0 if (k + 1 == len(keys)) else (k + 1) - t0, t1 = keys[k][1], keys[k][2] - alpha = 0.0 if t1 == t0 else (r - t0) / float(t1 - t0) - return (k, kn), alpha -``` diff --git a/docs/specs/missions.md b/docs/specs/missions.md deleted file mode 100644 index 6f351d0..0000000 --- a/docs/specs/missions.md +++ /dev/null @@ -1,5 +0,0 @@ -# Missions - -Документ описывает формат миссий и сценариев: начальное состояние, триггеры и связь миссий с картой мира. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `MisLoad.dll`. diff --git a/docs/specs/msh-animation.md b/docs/specs/msh-animation.md deleted file mode 100644 index 811fa00..0000000 --- a/docs/specs/msh-animation.md +++ /dev/null @@ -1,105 +0,0 @@ -# MSH animation - -Документ описывает анимационные ресурсы MSH: `Res8`, `Res19` и runtime-интерполяцию. - ---- - -## 1.13. Ресурсы анимации: Res8 и Res19 - -- **Res8** — массив анимационных ключей фиксированного размера 24 байта. -- **Res19** — `uint16` mapping‑массив «frame → keyIndex` (с per-node смещением). - -### 1.13.1. Формат Res8 (ключ 24 байта) - -```c -struct AnimKey24 { - float posX; // +0x00 - float posY; // +0x04 - float posZ; // +0x08 - float time; // +0x0C - int16_t qx; // +0x10 - int16_t qy; // +0x12 - int16_t qz; // +0x14 - int16_t qw; // +0x16 -}; -``` - -Декодирование quaternion-компонент: - -```c -q = s16 * (1.0f / 32767.0f) -``` - -### 1.13.2. Формат Res19 - -Res19 читается как непрерывный массив `uint16`: - -```c -uint16_t map[]; // размер = size(Res19)/2 -``` - -Per-node управление mapping'ом берётся из заголовка узла Res1: - -- `node.hdr2` (`Res1 + 0x04`) = `mapStart` (`0xFFFF` => map отсутствует); -- `node.hdr3` (`Res1 + 0x06`) = `fallbackKeyIndex` и одновременно верхняя граница валидного `map`‑значения. - -### 1.13.3. Выбор ключа для времени `t` (`sub_10012880`) - -1) Вычислить frame‑индекс: - -```c -frame = (int64)(t - 0.5f); // x87 FISTP-путь -``` - -Для строгой 1:1 эмуляции используйте именно поведение x87 `FISTP` (а не «упрощённый floor»), т.к. путь в оригинале опирается на FPU rounding mode. - -2) Проверка условий fallback: - -- `frame >= model.animFrameCount` (`model+0x9C`, из `NResEntry(Res19).attr2`); -- `mapStart == 0xFFFF`; -- `map[mapStart + frame] >= fallbackKeyIndex`. - -Если любое условие истинно: - -```c -keyIndex = fallbackKeyIndex; -``` - -Иначе: - -```c -keyIndex = map[mapStart + frame]; -``` - -3) Сэмплирование: - -- `k0 = Res8[keyIndex]` -- `k1 = Res8[keyIndex + 1]` (для интерполяции сегмента) - -Пути: - -- если `t == k0.time` → взять `k0`; -- если `t == k1.time` → взять `k1`; -- иначе `alpha = (t - k0.time) / (k1.time - k0.time)`, `pos = lerp(k0.pos, k1.pos, alpha)`, rotation смешивается через fastproc‑интерполятор quaternion. - -### 1.13.4. Межкадровое смешивание (`sub_10012560`) - -Функция смешивает два сэмпла (например, из двух animation time-позиций) с коэффициентом `blend`: - -1) получить два `(quat, pos)` через `sub_10012880`; -2) выполнить shortest‑path коррекцию знака quaternion: - -```c -if (|q0 + q1|^2 < |q0 - q1|^2) q1 = -q1; -``` - -3) смешать quaternion (fastproc) и построить orientation‑матрицу; -4) translation писать отдельно как `lerp(pos0, pos1, blend)` в ячейки `m[3], m[7], m[11]`. - -### 1.13.5. Что хранится в `Res19.attr2` - -При загрузке `sub_10015FD0` записывает `NResEntry(Res19).attr2` в `model+0x9C`. -Это поле используется как верхняя граница frame‑индекса в п.1.13.3. - ---- - diff --git a/docs/specs/msh-core.md b/docs/specs/msh-core.md deleted file mode 100644 index 82aec18..0000000 --- a/docs/specs/msh-core.md +++ /dev/null @@ -1,492 +0,0 @@ -# MSH core - -Документ описывает core-часть формата MSH: геометрию, узлы, батчи, LOD и slot-матрицу. - -Связанный формат контейнера: [NRes / RsLi](nres.md). - ---- - -## 1.1. Общая архитектура - -Модель состоит из набора именованных ресурсов внутри одного NRes‑архива. Каждый ресурс идентифицируется **целочисленным типом** (`resource_type`), который передаётся API функции `niReadData` (vtable‑метод `+0x18`) через связку `niFind` (vtable‑метод `+0x0C`, `+0x20`). - -Рендер‑модель использует **rigid‑скининг по узлам** (нет per‑vertex bone weights). Каждый batch геометрии привязан к одному узлу и рисуется с матрицей этого узла. - -## 1.2. Общая структура файла модели - -``` -┌────────────────────────────────────┐ -│ NRes‑заголовок (16 байт) │ -├────────────────────────────────────┤ -│ Ресурсы (произвольный порядок): │ -│ Res1 — Node table │ -│ Res2 — Model header + Slots │ -│ Res3 — Vertex positions │ -│ Res4 — Packed normals │ -│ Res5 — Packed UV0 │ -│ Res6 — Index buffer │ -│ Res7 — Triangle descriptors │ -│ Res8 — Keyframe data │ -│ Res10 — String table │ -│ Res13 — Batch table │ -│ Res19 — Animation mapping │ -│ [Res15] — UV1 / доп. поток │ -│ [Res16] — Tangent/Bitangent │ -│ [Res18] — Vertex color │ -│ [Res20] — Доп. таблица │ -├────────────────────────────────────┤ -│ NRes‑каталог │ -└────────────────────────────────────┘ -``` - -Ресурсы в квадратных скобках — **опциональные**. Загрузчик проверяет их наличие перед чтением (`niFindRes` возвращает `−1` при отсутствии). - -## 1.3. Порядок загрузки ресурсов (из `sub_10015FD0` в AniMesh.dll) - -Функция `sub_10015FD0` выполняет инициализацию внутренней структуры модели размером **0xA4** (164 байта). Ниже приведён точный порядок загрузки и маппинг ресурсов на поля структуры: - -| Шаг | Тип ресурса | Поле структуры | Описание | -|-----|-------------|----------------|-----------------------------------------| -| 1 | 1 | `+0x00` | Node table (Res1) | -| 2 | 2 | `+0x04` | Model header (Res2) | -| 3 | 3 | `+0x0C` | Vertex positions (Res3) | -| 4 | 4 | `+0x10` | Packed normals (Res4) | -| 5 | 5 | `+0x14` | Packed UV0 (Res5) | -| 6 | 10 (0x0A) | `+0x20` | String table (Res10) | -| 7 | 8 | `+0x18` | Keyframe / animation track data (Res8) | -| 8 | 19 (0x13) | `+0x1C` | Animation mapping (Res19) | -| 9 | 7 | `+0x24` | Triangle descriptors (Res7) | -| 10 | 13 (0x0D) | `+0x28` | Batch table (Res13) | -| 11 | 6 | `+0x2C` | Index buffer (Res6) | -| 12 | 15 (0x0F) | `+0x34` | Доп. vertex stream (Res15), опционально | -| 13 | 16 (0x10) | `+0x38` | Доп. vertex stream (Res16), опционально | -| 14 | 18 (0x12) | `+0x64` | Vertex color (Res18), опционально | -| 15 | 20 (0x14) | `+0x30` | Доп. таблица (Res20), опционально | - -### Производные поля (вычисляются после загрузки) - -| Поле | Формула | Описание | -|---------|-------------------------|------------------------------------------------------------------------------------------------| -| `+0x08` | `Res2_ptr + 0x8C` | Указатель на slot table (140 байт от начала Res2) | -| `+0x3C` | `= Res3_ptr` | Копия указателя positions (stream ptr) | -| `+0x40` | `= 0x0C` (12) | Stride позиций: `sizeof(float3)` | -| `+0x44` | `= Res4_ptr` | Копия указателя normals (stream ptr) | -| `+0x48` | `= 4` | Stride нормалей: 4 байта | -| `+0x4C` | `Res16_ptr` или `0` | Stream A Res16 (tangent) | -| `+0x50` | `= 8` если `+0x4C != 0` | Stride stream A (используется только при наличии Res16) | -| `+0x54` | `Res16_ptr + 4` или `0` | Stream B Res16 (bitangent) | -| `+0x58` | `= 8` если `+0x54 != 0` | Stride stream B (используется только при наличии Res16) | -| `+0x5C` | `= Res5_ptr` | Копия указателя UV0 (stream ptr) | -| `+0x60` | `= 4` | Stride UV0: 4 байта | -| `+0x68` | `= 4` или `0` | Stride Res18 (если найден) | -| `+0x8C` | `= Res15_ptr` | Копия указателя Res15 | -| `+0x90` | `= 8` | Stride Res15: 8 байт | -| `+0x94` | `= 0` | Зарезервировано/unk94: инициализируется нулём при загрузке; не является флагом Res18 | -| `+0x9C` | NRes entry Res19 `+8` | Метаданные из каталожной записи Res19 | -| `+0xA0` | NRes entry Res20 `+4` | Метаданные из каталожной записи Res20 (заполняется только если Res20 найден и открыт, иначе 0) | - -**Примечание к метаданным:** поле `+0x9C` читается из каталожной записи NRes для ресурса 19 (смещение `+8` в записи каталога, т.е. `attribute_2`). Поле `+0xA0` — из каталожной записи для ресурса 20 (смещение `+4`, т.е. `attribute_1`) **только если Res20 найден и `niOpenRes` вернул ненулевой указатель**; иначе `+0xA0 = 0`. Индекс записи определяется как `entry_index * 64`, после чего считывается поле. - ---- - -### 1.3.1. Ссылки на функции и паттерны вызовов (для проверки реверса) - -- `AniMesh.dll!sub_10015FD0` — загрузка ресурсов модели через vtable интерфейса NRes: - - `niFindRes(type, ...)` вызывается через `call [vtable+0x20]` - - `niOpenRes(...)` / чтение указателя — через `call [vtable+0x18]` -- `AniMesh.dll!sub_10015FD0` выставляет производные поля (`Res2_ptr+0x8C`, stride'ы), обнуляет `model+0x94`, и при отсутствии Res16 обнуляет только указатели потоков (`+0x4C`, `+0x54`). -- `AniMesh.dll!sub_10004840` / `sub_10004870` / `sub_100048A0` — использование runtime mapping‑таблицы (`+0x18`, индекс `boneId*4`) и таблицы указателей треков (`+0x08`) после построения анимационного объекта. - - -## 1.4. Ресурс Res2 — Model Header (140 байт) + Slot Table - -Ресурс Res2 содержит: - -``` -┌───────────────────────────────────┐ Смещение 0 -│ Model Header (140 байт = 0x8C) │ -├───────────────────────────────────┤ Смещение 140 (0x8C) -│ Slot Table │ -│ (slot_count × 68 байт) │ -└───────────────────────────────────┘ -``` - -### 1.4.1. Model Header (первые 140 байт) - -Поле `Res2[0x00..0x8B]` используется как **35 float** (без внутренних таблиц/индексов). Это подтверждено прямыми копированиями в `AniMesh.dll!sub_1000A460`: - -- `qmemcpy(this+0x54, Res2+0x00, 0x60)` — первые 24 float; -- копирование `Res2+0x60` размером `0x10` — ещё 4 float; -- `qmemcpy(this+0x134, Res2+0x70, 0x1C)` — ещё 7 float. - -Итоговая раскладка: - -| Диапазон | Размер | Тип | Семантика | -|--------------|--------|-------------|----------------------------------------------------------------------| -| `0x00..0x5F` | `0x60` | `float[24]` | 8 вершин глобального bounding‑hull (`vec3[8]`) | -| `0x60..0x6F` | `0x10` | `float[4]` | Глобальная bounding‑sphere: `center.xyz + radius` | -| `0x70..0x8B` | `0x1C` | `float[7]` | Глобальный «капсульный»/сегментный bound: `A.xyz`, `B.xyz`, `radius` | - -Для рендера и broadphase движок использует как слот‑bounds (`Res2 slot`), так и этот глобальный набор bounds (в зависимости от контекста вызова/LOD и наличия слота). - -### 1.4.2. Slot Table (массив записей по 68 байт) - -Slot — ключевая структура, связывающая узел иерархии с конкретной геометрией для конкретного LOD и группы. Каждая запись — **68 байт** (0x44). - -**Важно:** смещения в таблице ниже указаны в **десятичном формате** (байты). В скобках приведён hex‑эквивалент (например, 48 (0x30)). - - -| Смещение | Размер | Тип | Описание | -|-----------|--------|----------|-----------------------------------------------------| -| 0 | 2 | uint16 | `triStart` — индекс первого треугольника в Res7 | -| 2 | 2 | uint16 | `triCount` — длина диапазона треугольников (`Res7`) | -| 4 | 2 | uint16 | `batchStart` — индекс первого batch'а в Res13 | -| 6 | 2 | uint16 | `batchCount` — количество batch'ей | -| 8 | 4 | float | `aabbMin.x` | -| 12 | 4 | float | `aabbMin.y` | -| 16 | 4 | float | `aabbMin.z` | -| 20 | 4 | float | `aabbMax.x` | -| 24 | 4 | float | `aabbMax.y` | -| 28 | 4 | float | `aabbMax.z` | -| 32 | 4 | float | `sphereCenter.x` | -| 36 | 4 | float | `sphereCenter.y` | -| 40 | 4 | float | `sphereCenter.z` | -| 44 (0x2C) | 4 | float | `sphereRadius` | -| 48 (0x30) | 20 | 5×uint32 | Хвостовые поля: `unk30..unk40` (см. §1.4.2.1) | - -**AABB** — axis‑aligned bounding box в локальных координатах узла. -**Bounding Sphere** — описанная сфера в локальных координатах узла. - -#### 1.4.2.1. Точная семантика `triStart/triCount` - -В `AniMesh.dll!sub_1000B2C0` слот считается «владельцем» треугольника `triId`, если: - -```c -triId >= slot.triStart && triId < slot.triStart + slot.triCount -``` - -Это прямое доказательство, что `slot +0x02` — именно **count диапазона**, а не флаги. - -#### 1.4.2.2. Хвост слота (20 байт = 5×uint32) - -Последние 20 байт записи слота трактуем как 5 последовательных 32‑битных значений (little‑endian). Их назначение пока не подтверждено; для инструментов рекомендуется сохранять и восстанавливать их «как есть». - -- `+48 (0x30)`: `unk30` (uint32) -- `+52 (0x34)`: `unk34` (uint32) -- `+56 (0x38)`: `unk38` (uint32) -- `+60 (0x3C)`: `unk3C` (uint32) -- `+64 (0x40)`: `unk40` (uint32) - -Для culling при рендере: AABB/sphere трансформируются матрицей узла и инстанса. При неравномерном scale радиус сферы масштабируется по `max(scaleX, scaleY, scaleZ)` (подтверждено по коду). - ---- - -### 1.4.3. Восстановление счётчиков элементов по размерам ресурсов (практика для инструментов) - -Для toolchain надёжнее считать count'ы по размерам ресурсов (а не по дублирующим полям других таблиц). Это полностью совпадает с тем, как рантайм использует fixed stride'ы в `sub_10015FD0`. - -Берите **unpacked_size** (или фактический размер распакованного блока) соответствующего ресурса и вычисляйте: - -- `node_count` = `size(Res1) / 38` -- `vertex_count` = `size(Res3) / 12` -- `normals_count` = `size(Res4) / 4` -- `uv0_count` = `size(Res5) / 4` -- `index_count` = `size(Res6) / 2` -- `tri_count` = `index_count / 3` (если примитивы — список треугольников) -- `tri_desc_count` = `size(Res7) / 16` -- `batch_count` = `size(Res13) / 20` -- `slot_count` = `(size(Res2) - 0x8C) / 0x44` -- `anim_key_count` = `size(Res8) / 24` -- `anim_map_count` = `size(Res19) / 2` -- `uv1_count` = `size(Res15) / 8` (если Res15 присутствует) -- `tbn_count` = `size(Res16) / 8` (если Res16 присутствует; tangent/bitangent по 4 байта, stride 8) -- `color_count` = `size(Res18) / 4` (если Res18 присутствует) - -**Валидация:** - -- Любое деление должно быть **без остатка**; иначе ресурс повреждён или stride неверно угадан. -- Если присутствуют Res4/Res5/Res15/Res16/Res18, их count'ы по смыслу должны совпадать с `vertex_count` (или быть ≥ него, если формат допускает хвостовые данные — пока не наблюдалось). -- Для `slot_count` дополнительно проверьте, что `size(Res2) >= 0x8C`. - -**Проверка на реальных данных (435 MSH):** - -- `Res2.attr1 == (size-140)/68`, `Res2.attr2 == 0`, `Res2.attr3 == 68`; -- `Res7.attr1 == size/16`, `Res7.attr3 == 16`; -- `Res8.attr1 == size/24`, `Res8.attr3 == 4`; -- `Res19.attr1 == size/2`, `Res19.attr3 == 2`; -- для `Res1` почти всегда `attr3 == 38` (один служебный outlier: `MTCHECK.MSH` с `attr3 == 24`). - -Эти формулы достаточны, чтобы реализовать распаковщик/просмотрщик геометрии и батчей даже без полного понимания полей заголовка Res2. - -## 1.5. Ресурс Res1 — Node Table (38 байт на узел) - -Node table — компактная карта слотов по уровням LOD и группам. Каждый узел занимает **38 байт** (19 × `uint16`). - -### Адресация слота - -Движок вычисляет индекс слова в таблице: - -``` -word_index = nodeIndex × 19 + lod × 5 + group + 4 -slot_index = node_table[word_index] // uint16, 0xFFFF = нет слота -``` - -Параметры: - -- `lod`: 0..2 (три уровня детализации). Значение `−1` → подставляется `current_lod` из инстанса. -- `group`: 0..4 (пять групп). На практике чаще всего используется `group = 0`. - -### Раскладка записи узла (38 байт) - -``` -┌───────────────────────────────────────────────────────┐ -│ Header: 4 × uint16 (8 байт) │ -│ hdr0, hdr1, hdr2, hdr3 │ -├───────────────────────────────────────────────────────┤ -│ SlotIndex matrix: 3 LOD × 5 groups = 15 × uint16 │ -│ LOD 0: group[0..4] │ -│ LOD 1: group[0..4] │ -│ LOD 2: group[0..4] │ -└───────────────────────────────────────────────────────┘ -``` - -| Смещение | Размер | Тип | Описание | -|----------|--------|------------|-----------------------------------------| -| 0 | 8 | uint16[4] | Заголовок узла (`hdr0..hdr3`, см. ниже) | -| 8 | 30 | uint16[15] | Матрица слотов: `slotIndex[lod][group]` | - -`slotIndex = 0xFFFF` означает «слот отсутствует» — узел при данном LOD и группе не рисуется. - -Подтверждённые семантики полей `hdr*`: - -- `hdr1` (`+0x02`) — parent/index-link при построении инстанса (в `sub_1000A460` читается как индекс связанного узла, `0xFFFF` = нет связи). -- `hdr2` (`+0x04`) — `mapStart` для Res19 (`0xFFFF` = нет карты; fallback по `hdr3`). -- `hdr3` (`+0x06`) — `fallbackKeyIndex`/верхняя граница для map‑значений (используется в `sub_10012880`). - -`hdr0` (`+0x00`) по коду участвует в битовых проверках (`&0x40`, `byte+1 & 8`) и несёт флаги узла. - -**Группы (group 0..4):** в рантайме это ортогональный индекс к LOD (матрица 5×3 на узел). Имена групп в оригинальных ресурсах не подписаны; для 1:1 нужно сохранять группы как «сырой» индекс 0..4 без переинтерпретации. - ---- - -## 1.6. Ресурс Res3 — Vertex Positions - -**Формат:** массив `float3` (IEEE 754 single‑precision). -**Stride:** 12 байт. - -```c -struct Position { - float x; // +0 - float y; // +4 - float z; // +8 -}; -``` - -Чтение: `pos = *(float3*)(res3_data + 12 * vertexIndex)`. - ---- - -## 1.7. Ресурс Res4 — Packed Normals - -**Формат:** 4 байта на вершину. -**Stride:** 4 байта. - -```c -struct PackedNormal { - int8_t nx; // +0 - int8_t ny; // +1 - int8_t nz; // +2 - int8_t nw; // +3 (назначение не подтверждено: паддинг / знак / индекс) -}; -``` - -### Алгоритм декодирования (подтверждено по AniMesh.dll) - -> В движке используется делитель **127.0**, а не 128.0 (см. константу `127.0` рядом с `1024.0`/`32767.0`). - -``` -normal.x = clamp((float)nx / 127.0, -1.0, 1.0) -normal.y = clamp((float)ny / 127.0, -1.0, 1.0) -normal.z = clamp((float)nz / 127.0, -1.0, 1.0) -``` - -**Множитель:** `1.0 / 127.0 ≈ 0.0078740157`. -**Диапазон входных значений:** −128..+127 → выход ≈ −1.007874..+1.0 → **после клампа** −1.0..+1.0. -**Почему нужен кламп:** значение `-128` при делении на `127.0` даёт модуль чуть больше 1. -**4‑й байт (nw):** используется ли он как часть нормали, как индекс или просто как выравнивание — не подтверждено. Рекомендация: игнорировать при первичном импорте. - ---- - -## 1.8. Ресурс Res5 — Packed UV0 - -**Формат:** 4 байта на вершину (два `int16`). -**Stride:** 4 байта. - -```c -struct PackedUV { - int16_t u; // +0 - int16_t v; // +2 -}; -``` - -### Алгоритм декодирования - -``` -uv.u = (float)u / 1024.0 -uv.v = (float)v / 1024.0 -``` - -**Множитель:** `1.0 / 1024.0 = 0.0009765625`. -**Диапазон входных значений:** −32768..+32767 → выход ≈ −32.0..+31.999. -Значения >1.0 или <0.0 означают wrapping/repeat текстурных координат. - -### Алгоритм кодирования (для экспортёра) - -``` -packed_u = (int16_t)round(uv.u * 1024.0) -packed_v = (int16_t)round(uv.v * 1024.0) -``` - -Результат обрезается (clamp) до диапазона `int16` (−32768..+32767). - ---- - -## 1.9. Ресурс Res6 — Index Buffer - -**Формат:** массив `uint16` (беззнаковые 16‑битные индексы). -**Stride:** 2 байта. - -Максимальное число вершин в одном batch: 65535. -Индексы используются совместно с `baseVertex` из batch table: - -``` -actual_vertex_index = index_buffer[indexStart + i] + baseVertex -``` - ---- - -## 1.10. Ресурс Res7 — Triangle Descriptors - -**Формат:** массив записей по 16 байт. Одна запись на треугольник. - -| Смещение | Размер | Тип | Описание | -|----------|--------|----------|---------------------------------------------| -| `+0x00` | 2 | `uint16` | `triFlags` — фильтрация/материал tri‑уровня | -| `+0x02` | 2 | `uint16` | `linkTri0` — tri‑ref для связанного обхода | -| `+0x04` | 2 | `uint16` | `linkTri1` — tri‑ref для связанного обхода | -| `+0x06` | 2 | `uint16` | `linkTri2` — tri‑ref для связанного обхода | -| `+0x08` | 2 | `int16` | `nX` (packed, scale `1/32767`) | -| `+0x0A` | 2 | `int16` | `nY` (packed, scale `1/32767`) | -| `+0x0C` | 2 | `int16` | `nZ` (packed, scale `1/32767`) | -| `+0x0E` | 2 | `uint16` | `selPacked` — 3 селектора по 2 бита | - -Расшифровка `selPacked` (`AniMesh.dll!sub_10013680`): - -```c -sel0 = selPacked & 0x3; if (sel0 == 3) sel0 = 0xFFFF; -sel1 = (selPacked >> 2) & 0x3; if (sel1 == 3) sel1 = 0xFFFF; -sel2 = (selPacked >> 4) & 0x3; if (sel2 == 3) sel2 = 0xFFFF; -``` - -`linkTri*` передаются в `sub_1000B2C0` и используются для построения соседнего набора треугольников при коллизии/пикинге. - -**Важно:** дескрипторы не хранят индексы вершин треугольника. Индексы берутся из Res6 (index buffer) через `indexStart`/`indexCount` соответствующего batch'а. - -Дескрипторы используются при обходе треугольников для коллизии и пикинга. `triStart` из slot table указывает, с какого дескриптора начинать обход для данного слота. - ---- - -## 1.11. Ресурс Res13 — Batch Table - -**Формат:** массив записей по 20 байт. Batch — минимальная единица отрисовки. - -| Смещение | Размер | Тип | Описание | -|----------|--------|--------|---------------------------------------------------------| -| 0 | 2 | uint16 | `batchFlags` — битовая маска для фильтрации | -| 2 | 2 | uint16 | `materialIndex` — индекс материала | -| 4 | 2 | uint16 | `unk4` — неподтверждённое поле | -| 6 | 2 | uint16 | `unk6` — вероятный `nodeIndex` (привязка batch к кости) | -| 8 | 2 | uint16 | `indexCount` — число индексов (кратно 3) | -| 10 | 4 | uint32 | `indexStart` — стартовый индекс в Res6 (в элементах) | -| 14 | 2 | uint16 | `unk14` — неподтверждённое поле | -| 16 | 4 | uint32 | `baseVertex` — смещение вершинного индекса | - -### Использование при рендере - -``` -for i in 0 .. indexCount-1: - raw_index = index_buffer[indexStart + i] - vertex_index = raw_index + baseVertex - position = res3[vertex_index] - normal = decode_normal(res4[vertex_index]) - uv = decode_uv(res5[vertex_index]) -``` - -**Примечание:** движок читает `indexStart` как `uint32` и умножает на 2 для получения байтового смещения в массиве `uint16`. - ---- - -## 1.12. Ресурс Res10 — String Table - -Res10 — это **последовательность записей, индексируемых по `nodeIndex`** (см. `AniMesh.dll!sub_10012530`). - -Формат одной записи: - -```c -struct Res10Record { - uint32_t len; // число символов без терминирующего '\0' - char text[]; // если len > 0: хранится len+1 байт (включая '\0') - // если len == 0: payload отсутствует -}; -``` - -Переход к следующей записи: - -```c -next = cur + 4 + (len ? (len + 1) : 0); -``` - -`sub_10012530` возвращает: - -- `NULL`, если `len == 0`; -- `record + 4`, если `len > 0` (указатель на C‑строку). - -Это значение используется в `sub_1000A460` для проверки имени текущего узла (например, поиск подстроки `"central"` при обработке node‑флагов). - ---- - - ---- - -## 1.14. Опциональные vertex streams - -### Res15 — Дополнительный vertex stream (stride 8) - -- **Stride:** 8 байт на вершину. -- **Кандидаты:** `float2 uv1` (lightmap / second UV layer), 4 × `int16` (2 UV‑пары), либо иной формат. -- Загружается условно — если ресурс 15 отсутствует, указатель равен `NULL`. - -### Res16 — Tangent / Bitangent (stride 8, split 2×4) - -- **Stride:** 8 байт на вершину (2 подпотока по 4 байта). -- При загрузке движок создаёт **два перемежающихся (interleaved) подпотока**: - - Stream A: `base + 0`, stride 8 — 4 байта (кандидат: packed tangent, `int8 × 4`) - - Stream B: `base + 4`, stride 8 — 4 байта (кандидат: packed bitangent, `int8 × 4`) -- Если ресурс 16 отсутствует, оба указателя обнуляются. -- **Важно:** в оригинальном `sub_10015FD0` при отсутствии Res16 страйды `+0x50/+0x58` явным образом не обнуляются; это безопасно, потому что оба указателя равны `NULL` и код не должен обращаться к потокам без проверки указателя. -- Декодирование предположительно аналогично нормалям: `component / 127.0` (как Res4), но требует подтверждения; при импорте — кламп в [-1..1]. - -### Res18 — Vertex Color (stride 4) - -- **Stride:** 4 байта на вершину. -- **Кандидаты:** `D3DCOLOR` (BGRA), packed параметры освещения, vertex AO. -- Загружается условно (через проверку `niFindRes` на возврат `−1`). - -### Res20 — Дополнительная таблица - -- Присутствует не всегда. -- Из каталожной записи NRes считывается поле `attribute_1` (смещение `+4`) и сохраняется как метаданные. -- **Кандидаты:** vertex remap, дополнительные данные для эффектов/деформаций. - ---- - diff --git a/docs/specs/msh-notes.md b/docs/specs/msh-notes.md deleted file mode 100644 index 1bd4808..0000000 --- a/docs/specs/msh-notes.md +++ /dev/null @@ -1,277 +0,0 @@ -# 3D implementation notes - -Контрольные заметки, сводки алгоритмов и остаточные семантические вопросы по 3D-подсистемам. - ---- - -## 5.1. Порядок байт - -Все значения хранятся в **little‑endian** порядке (платформа x86/Win32). - -## 5.2. Выравнивание - -- **NRes‑ресурсы:** данные каждого ресурса внутри NRes‑архива выровнены по границе **8 байт** (0‑padding). -- **Внутренняя структура ресурсов:** таблицы Res1/Res2/Res7/Res13 не имеют межзаписевого выравнивания — записи идут подряд. -- **Vertex streams:** stride'ы фиксированы (12/4/8 байт) — вершинные данные идут подряд без паддинга. - -## 5.3. Размеры записей на диске - -| Ресурс | Запись | Размер (байт) | Stride | -|--------|-----------|---------------|-------------------------| -| Res1 | Node | 38 | 38 (19×u16) | -| Res2 | Slot | 68 | 68 | -| Res3 | Position | 12 | 12 (3×f32) | -| Res4 | Normal | 4 | 4 (4×s8) | -| Res5 | UV0 | 4 | 4 (2×s16) | -| Res6 | Index | 2 | 2 (u16) | -| Res7 | TriDesc | 16 | 16 | -| Res8 | AnimKey | 24 | 24 | -| Res10 | StringRec | переменный | `4 + (len ? len+1 : 0)` | -| Res13 | Batch | 20 | 20 | -| Res19 | AnimMap | 2 | 2 (u16) | -| Res15 | VtxStr | 8 | 8 | -| Res16 | VtxStr | 8 | 8 (2×4) | -| Res18 | VtxStr | 4 | 4 | - -## 5.4. Вычисление количества элементов - -Количество записей вычисляется из размера ресурса: - -``` -count = resource_data_size / record_stride -``` - -Например: - -- `vertex_count = res3_size / 12` -- `index_count = res6_size / 2` -- `batch_count = res13_size / 20` -- `slot_count = (res2_size - 140) / 68` -- `node_count = res1_size / 38` -- `tri_desc_count = res7_size / 16` -- `anim_key_count = res8_size / 24` -- `anim_map_count = res19_size / 2` - -Для Res10 нет фиксированного stride: нужно последовательно проходить записи `u32 len` + `(len ? len+1 : 0)` байт. - -## 5.5. Идентификация ресурсов в NRes - -Ресурсы модели идентифицируются по полю `type` (смещение 0) в каталожной записи NRes. Загрузчик использует `niFindRes(archive, type, subtype)` для поиска, где `type` — число (1, 2, 3, ... 20), а `subtype` (byte) — уточнение (из аргумента загрузчика). - -## 5.6. Минимальный набор для рендера - -Для статической модели без анимации достаточно: - -| Ресурс | Обязательность | -|--------|------------------------------------------------| -| Res1 | Да | -| Res2 | Да | -| Res3 | Да | -| Res4 | Рекомендуется | -| Res5 | Рекомендуется | -| Res6 | Да | -| Res7 | Для коллизии | -| Res13 | Да | -| Res10 | Желательно (узловые имена/поведенческие ветки) | -| Res8 | Нет (анимация) | -| Res19 | Нет (анимация) | -| Res15 | Нет | -| Res16 | Нет | -| Res18 | Нет | -| Res20 | Нет | - -## 5.7. Сводка алгоритмов декодирования - -### Позиции (Res3) - -```python -def decode_position(data, vertex_index): - offset = vertex_index * 12 - x = struct.unpack_from('<f', data, offset)[0] - y = struct.unpack_from('<f', data, offset + 4)[0] - z = struct.unpack_from('<f', data, offset + 8)[0] - return (x, y, z) -``` - -### Нормали (Res4) - -```python -def decode_normal(data, vertex_index): - offset = vertex_index * 4 - nx = struct.unpack_from('<b', data, offset)[0] # int8 - ny = struct.unpack_from('<b', data, offset + 1)[0] - nz = struct.unpack_from('<b', data, offset + 2)[0] - # nw = data[offset + 3] # не используется - return ( - max(-1.0, min(1.0, nx / 127.0)), - max(-1.0, min(1.0, ny / 127.0)), - max(-1.0, min(1.0, nz / 127.0)), - ) -``` - -### UV‑координаты (Res5) - -```python -def decode_uv(data, vertex_index): - offset = vertex_index * 4 - u = struct.unpack_from('<h', data, offset)[0] # int16 - v = struct.unpack_from('<h', data, offset + 2)[0] - return (u / 1024.0, v / 1024.0) -``` - -### Кодирование нормали (для экспортёра) - -```python -def encode_normal(nx, ny, nz): - return ( - max(-128, min(127, int(round(nx * 127.0)))), - max(-128, min(127, int(round(ny * 127.0)))), - max(-128, min(127, int(round(nz * 127.0)))), - 0 # nw = 0 (безопасное значение) - ) -``` - -### Кодирование UV (для экспортёра) - -```python -def encode_uv(u, v): - return ( - max(-32768, min(32767, int(round(u * 1024.0)))), - max(-32768, min(32767, int(round(v * 1024.0)))) - ) -``` - -### Строки узлов (Res10) - -```python -def parse_res10_for_nodes(buf: bytes, node_count: int) -> list[str | None]: - out = [] - off = 0 - for _ in range(node_count): - ln = struct.unpack_from('<I', buf, off)[0] - off += 4 - if ln == 0: - out.append(None) - continue - raw = buf[off:off + ln + 1] # len + '\0' - out.append(raw[:-1].decode('ascii', errors='replace')) - off += ln + 1 - return out -``` - -### Ключ анимации (Res8) и mapping (Res19) - -```python -def decode_anim_key24(buf: bytes, idx: int): - o = idx * 24 - px, py, pz, t = struct.unpack_from('<4f', buf, o) - qx, qy, qz, qw = struct.unpack_from('<4h', buf, o + 16) - s = 1.0 / 32767.0 - return (px, py, pz), t, (qx * s, qy * s, qz * s, qw * s) -``` - -### Эффектный поток (FXID) - -```python -FX_CMD_SIZE = {1:224,2:148,3:200,4:204,5:112,6:4,7:208,8:248,9:208,10:208} - -def parse_fx_payload(raw: bytes): - cmd_count = struct.unpack_from('<I', raw, 0)[0] - ptr = 0x3C - cmds = [] - for _ in range(cmd_count): - w = struct.unpack_from('<I', raw, ptr)[0] - op = w & 0xFF - enabled = (w >> 8) & 1 - size = FX_CMD_SIZE[op] - cmds.append((op, enabled, ptr, size)) - ptr += size - if ptr != len(raw): - raise ValueError('tail bytes after command stream') - return cmds -``` - -### Texm (header + mips + Page) - -```python -def parse_texm(raw: bytes): - magic, w, h, mips, f4, f5, unk6, fmt = struct.unpack_from('<8I', raw, 0) - assert magic == 0x6D786554 # 'Texm' - bpp = 1 if fmt == 0 else (2 if fmt in (565, 556, 4444) else 4) - pix_sum = 0 - mw, mh = w, h - for _ in range(mips): - pix_sum += mw * mh - mw = max(1, mw >> 1) - mh = max(1, mh >> 1) - off = 32 + (1024 if fmt == 0 else 0) + bpp * pix_sum - page = None - if off + 8 <= len(raw) and raw[off:off+4] == b'Page': - n = struct.unpack_from('<I', raw, off + 4)[0] - page = [struct.unpack_from('<4h', raw, off + 8 + i * 8) for i in range(n)] - return (w, h, mips, fmt, f4, f5, unk6, page) -``` - ---- - -# Часть 6. Остаточные семантические вопросы - -Пункты ниже **не блокируют 1:1-парсинг/рендер/интерполяцию** (все бинарные структуры уже определены), но их человеко‑читаемая трактовка может быть уточнена дополнительно. - -## 6.1. Batch table — смысл `unk4/unk6/unk14` - -Физическое расположение полей известно, но доменное имя/назначение не зафиксировано: - -- `unk4` (`+0x04`) -- `unk6` (`+0x06`) -- `unk14` (`+0x0E`) - -## 6.2. Node flags и имена групп - -- Биты в `Res1.hdr0` используются в ряде рантайм‑веток, но их «геймдизайн‑имена» неизвестны. -- Для group‑индекса `0..4` не найдено текстовых label'ов в ресурсах; для совместимости нужно сохранять числовой индекс как есть. - -## 6.3. Slot tail `unk30..unk40` - -Хвост слота (`+0x30..+0x43`, `5×uint32`) стабильно присутствует в формате, но движок не делает явной семантической декомпозиции этих пяти слов в path'ах загрузки/рендера/коллизии. - -## 6.4. Effect command payload semantics - -Container/stream формально полностью восстановлен (header, opcode, размеры, инстанцирование). Остаётся необязательная задача: дать «человеко‑читаемые» имена каждому полю внутри payload конкретных opcode. - -## 6.5. Поля `TexmHeader.flags4/flags5/unk6` - -Бинарный layout и декодер известны, но значения этих трёх полей в контенте используются контекстно; для 1:1 достаточно хранить/восстанавливать их без модификации. - -## 6.6. Что пока не хватает для полноценного обратного экспорта (`OBJ -> MSH/NRes`) - -Ниже перечислено то, что нужно закрыть для **lossless round-trip** и 1:1‑поведения при импорте внешней геометрии обратно в формат игры. - -### A) Неполная «авторская» семантика бинарных таблиц - -1. `Res2` header (`первые 0x8C`): не зафиксированы все поля и правила их вычисления при генерации нового файла (а не copy-through из оригинала). -2. `Res7` tri-descriptor: для 16‑байтной записи декодирован базовый каркас, но остаётся неформализованной часть служебных бит/полей, нужных для стабильной генерации adjacency/служебной топологии. -3. `Res13` поля `unk4/unk6/unk14`: для парсинга достаточно, но для генерации «канонических» значений из голого `OBJ` правила не определены. -4. `Res2` slot tail (`unk30..unk40`): семантика не разложена, поэтому при экспорте новых ассетов нет детерминированной формулы заполнения. - -### B) Анимационный path ещё не закрыт как writer - -1. Нужен полный writer для `Res8/Res19`: - - точная спецификация байтового формата на запись; - - правила генерации mapping (`Res19`) по узлам/кадрам; - - жёсткая фиксация округления как в x87 path (включая edge-case на границах кадра). -2. Правила биндинга узлов/строк (`Res10`) и `slotFlags` к runtime‑сущностям пока описаны частично и требуют формализации именно для импорта новых данных. - -### C) Материалы, текстуры, эффекты для «полного ассета» - -1. Для `Texm` не завершён writer, покрывающий все используемые режимы (включая palette path, mip-chain, `Page`, и правила заполнения служебных полей). -2. Для `FXID` известен контейнер/длины команд, но не завершена field-level семантика payload всех opcode для генерации новых эффектов, эквивалентных оригинальному пайплайну. -3. Экспорт только `OBJ` покрывает геометрию; для игрового ассета нужен sidecar-слой (материалы/текстуры/эффекты/анимация), иначе импорт неизбежно неполный. - -### D) Что это означает на практике - -1. `OBJ -> MSH` сейчас реалистичен как **ограниченный static-экспорт** (позиции/индексы/часть batch/slot структуры). -2. `OBJ -> полноценный игровой ресурс` (без потерь, с поведением 1:1) пока недостижим без закрытия пунктов A/B/C. -3. До закрытия пунктов A/B/C рекомендуется использовать режим: - - геометрия экспортируется из `OBJ`; - - неизвестные/служебные поля берутся copy-through из референсного оригинального ассета той же структуры. diff --git a/docs/specs/msh.md b/docs/specs/msh.md deleted file mode 100644 index e2623f8..0000000 --- a/docs/specs/msh.md +++ /dev/null @@ -1,22 +0,0 @@ -# Форматы 3D-ресурсов движка NGI - -Этот документ теперь является обзором и точкой входа в набор отдельных спецификаций. - -## Структура спецификаций - -1. [MSH core](msh-core.md) — геометрия, узлы, батчи, LOD, slot-матрица. -2. [MSH animation](msh-animation.md) — `Res8`, `Res19`, выбор ключей и интерполяция. -3. [Materials + Texm](materials-texm.md) — материалы, текстуры, палитры, `WEAR`, `LIGHTMAPS`, `Texm`. -4. [FXID](fxid.md) — контейнер эффекта и команды runtime-потока. -5. [Terrain + map loading](terrain-map-loading.md) — ландшафт, шейдинг и привязка к миру. -6. [Runtime pipeline](runtime-pipeline.md) — межмодульное поведение движка в кадре. -7. [3D implementation notes](msh-notes.md) — контрольные заметки, декодирование и открытые вопросы. - -## Связанные спецификации - -- [NRes / RsLi](nres.md) - -## Принцип декомпозиции - -- Форматы и контейнеры документируются отдельно, чтобы их можно было верифицировать и править независимо. -- Runtime-пайплайн вынесен в отдельный документ, потому что пересекает несколько DLL и не является форматом на диске. diff --git a/docs/specs/network.md b/docs/specs/network.md deleted file mode 100644 index 1950e8a..0000000 --- a/docs/specs/network.md +++ /dev/null @@ -1,5 +0,0 @@ -# Network system - -Документ описывает сетевую подсистему: протокол обмена, синхронизацию состояния и сетевую архитектуру (client-server/P2P). - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга `Net.dll`. diff --git a/docs/specs/nres.md b/docs/specs/nres.md deleted file mode 100644 index 32ccb1b..0000000 --- a/docs/specs/nres.md +++ /dev/null @@ -1,718 +0,0 @@ -# Форматы игровых ресурсов - -## Обзор - -Библиотека `Ngi32.dll` реализует два различных формата архивов ресурсов: - -1. **NRes** — основной формат архива ресурсов, используемый через API `niOpenResFile` / `niCreateResFile`. Каталог файлов расположен в **конце** файла. Поддерживает создание, редактирование, добавление и удаление записей. - -2. **RsLi** — формат библиотеки ресурсов, используемый через API `rsOpenLib` / `rsLoad`. Таблица записей расположена **в начале** файла (сразу после заголовка) и зашифрована XOR-шифром. Поддерживает несколько методов сжатия. Только чтение. - ---- - -## Часть 1. Формат NRes - -### 1.1. Общая структура файла - -``` -┌──────────────────────────┐ Смещение 0 -│ Заголовок (16 байт) │ -├──────────────────────────┤ Смещение 16 -│ │ -│ Данные ресурсов │ -│ (выровнены по 8 байт) │ -│ │ -├──────────────────────────┤ Смещение = total_size - entry_count × 64 -│ Каталог записей │ -│ (entry_count × 64 байт) │ -└──────────────────────────┘ Смещение = total_size -``` - -### 1.2. Заголовок файла (16 байт) - -| Смещение | Размер | Тип | Значение | Описание | -| -------- | ------ | ------- | ------------------- | ------------------------------------ | -| 0 | 4 | char[4] | `NRes` (0x4E526573) | Магическая сигнатура (little-endian) | -| 4 | 4 | uint32 | `0x00000100` (256) | Версия формата (1.0) | -| 8 | 4 | int32 | — | Количество записей в каталоге | -| 12 | 4 | int32 | — | Полный размер файла в байтах | - -**Валидация при открытии:** магическая сигнатура и версия должны совпадать точно. Поле `total_size` (смещение 12) **проверяется на равенство** с фактическим размером файла (`GetFileSize`). Если значения не совпадают — файл отклоняется. - -### 1.3. Положение каталога в файле - -Каталог располагается в самом конце файла. Его смещение вычисляется по формуле: - -``` -directory_offset = total_size - entry_count × 64 -``` - -Данные ресурсов занимают пространство между заголовком (16 байт) и каталогом. - -### 1.4. Запись каталога (64 байта) - -Каждая запись каталога занимает ровно **64 байта** (0x40): - -| Смещение | Размер | Тип | Описание | -| -------- | ------ | -------- | ------------------------------------------------- | -| 0 | 4 | uint32 | Тип / идентификатор ресурса | -| 4 | 4 | uint32 | Атрибут 1 (например, формат, дата, категория) | -| 8 | 4 | uint32 | Атрибут 2 (например, подтип, метка времени) | -| 12 | 4 | uint32 | Размер данных ресурса в байтах | -| 16 | 4 | uint32 | Атрибут 3 (дополнительный параметр) | -| 20 | 36 | char[36] | Имя файла (null-terminated, макс. 35 символов) | -| 56 | 4 | uint32 | Смещение данных от начала файла | -| 60 | 4 | uint32 | Индекс сортировки (для двоичного поиска по имени) | - -#### Поле «Имя файла» (смещение 20, 36 байт) - -- Максимальная длина имени: **35 символов** + 1 байт null-терминатор. -- При записи поле сначала обнуляется (`memset(0, 36 байт)`), затем копируется имя (`strncpy`, макс. 35 символов). -- Поиск по имени выполняется **без учёта регистра** (`_strcmpi`). - -#### Поле «Индекс сортировки» (смещение 60) - -Используется для **двоичного поиска по имени**. Содержит индекс оригинальной записи, отсортированной в алфавитном порядке (регистронезависимо). Индекс строится при сохранении файла функцией `sub_10013260` с помощью **пузырьковой сортировки** по именам. - -**Алгоритм поиска** (`sub_10011E60`): классический двоичный поиск по отсортированному массиву индексов. Возвращает оригинальный индекс записи или `-1` при отсутствии. - -#### Поле «Смещение данных» (смещение 56) - -Абсолютное смещение от начала файла. Данные читаются из mapped view: `pointer = mapped_base + data_offset`. - -### 1.5. Выравнивание данных - -При добавлении ресурса его данные записываются последовательно, после чего выполняется **выравнивание по 8-байтной границе**: - -```c -padding = ((data_size + 7) & ~7) - data_size; -// Если padding > 0, записываются нулевые байты -``` - -Таким образом, каждый блок данных начинается с адреса, кратного 8. - -При изменении размера данных ресурса выполняется сдвиг всех последующих данных и обновление смещений всех затронутых записей каталога. - -### 1.6. Создание файла (API `niCreateResFile`) - -При создании нового файла: - -1. Если файл уже существует и содержит корректный NRes-архив, существующий каталог считывается с конца файла, а файл усекается до начала каталога. -2. Если файл пуст или не является NRes-архивом, создаётся новый с пустым каталогом. Поля `entry_count = 0`, `total_size = 16`. - -При закрытии файла (`sub_100122D0`): - -1. Заголовок переписывается в начало файла (16 байт). -2. Вычисляется `total_size = data_end_offset + entry_count × 64`. -3. Индексы сортировки пересчитываются. -4. Каталог записей записывается в конец файла. - -### 1.7. Режимы сортировки каталога - -Функция `sub_10012560` поддерживает 12 режимов сортировки (0–11): - -| Режим | Порядок сортировки | -| ----- | --------------------------------- | -| 0 | Без сортировки (сброс) | -| 1 | По атрибуту 1 (смещение 4) | -| 2 | По атрибуту 2 (смещение 8) | -| 3 | По (атрибут 1, атрибут 2) | -| 4 | По типу ресурса (смещение 0) | -| 5 | По (тип, атрибут 1) | -| 6 | По (тип, атрибут 1) — идентичен 5 | -| 7 | По (тип, атрибут 1, атрибут 2) | -| 8 | По имени (регистронезависимо) | -| 9 | По (тип, имя) | -| 10 | По (атрибут 1, имя) | -| 11 | По (атрибут 2, имя) | - -### 1.8. Операция `niOpenResFileEx` — флаги открытия - -Второй параметр — битовые флаги: - -| Бит | Маска | Описание | -| --- | ----- | ----------------------------------------------------------------------------------- | -| 0 | 0x01 | Sequential scan hint (`FILE_FLAG_SEQUENTIAL_SCAN` вместо `FILE_FLAG_RANDOM_ACCESS`) | -| 1 | 0x02 | Открыть для записи (read-write). Без флага — только чтение | -| 2 | 0x04 | Пометить файл как «кэшируемый» (не выгружать при refcount=0) | -| 3 | 0x08 | Raw-режим: не проверять заголовок NRes, трактовать весь файл как единый ресурс | - -### 1.9. Виртуальное касание страниц - -Функция `sub_100197D0` выполняет «касание» страниц памяти для принудительной загрузки из memory-mapped файла. Она обходит адресное пространство с шагом 4096 байт (размер страницы), начиная с 0x10000 (64 КБ): - -``` -for (result = 0x10000; result < size; result += 4096); -``` - -Вызывается при чтении данных ресурса с флагом `a3 != 0` для предзагрузки данных в оперативную память. - ---- - -## Часть 2. Формат RsLi - -### 2.1. Общая структура файла - -``` -┌───────────────────────────────┐ Смещение 0 -│ Заголовок файла (32 байта) │ -├───────────────────────────────┤ Смещение 32 -│ Таблица записей (зашифрована)│ -│ (entry_count × 32 байт) │ -├───────────────────────────────┤ Смещение 32 + entry_count × 32 -│ │ -│ Данные ресурсов │ -│ │ -├───────────────────────────────┤ -│ [Опциональный трейлер — 6 б] │ -└───────────────────────────────┘ -``` - -### 2.2. Заголовок файла (32 байта) - -| Смещение | Размер | Тип | Значение | Описание | -| -------- | ------ | ------- | ----------------- | --------------------------------------------- | -| 0 | 2 | char[2] | `NL` (0x4C4E) | Магическая сигнатура | -| 2 | 1 | uint8 | `0x00` | Зарезервировано (должно быть 0) | -| 3 | 1 | uint8 | `0x01` | Версия формата | -| 4 | 2 | int16 | — | Количество записей (sign-extended при чтении) | -| 6 | 8 | — | — | Зарезервировано / не используется | -| 14 | 2 | uint16 | `0xABBA` или иное | Флаг предсортировки (см. ниже) | -| 16 | 4 | — | — | Зарезервировано | -| 20 | 4 | uint32 | — | **Начальное состояние XOR-шифра** (seed) | -| 24 | 8 | — | — | Зарезервировано | - -#### Флаг предсортировки (смещение 14) - -- Если `*(uint16*)(header + 14) == 0xABBA` — движок **не строит** таблицу индексов в памяти. Значения `entry[i].sort_to_original` используются **как есть** (и для двоичного поиска, и как XOR‑ключ для данных). -- Если значение **отлично от 0xABBA** — после загрузки выполняется **пузырьковая сортировка** имён и строится перестановка `sort_to_original[]`, которая затем **записывается в `entry[i].sort_to_original`**, перетирая значения из файла. Именно эта перестановка далее используется и для поиска, и как XOR‑ключ (младшие 16 бит). - -### 2.3. XOR-шифр таблицы записей - -Таблица записей начинается со смещения 32 и зашифрована поточным XOR-шифром. Ключ инициализируется из DWORD по смещению 20 заголовка. - -#### Начальное состояние - -``` -seed = *(uint32*)(header + 20) -lo = seed & 0xFF // Младший байт -hi = (seed >> 8) & 0xFF // Второй байт -``` - -#### Алгоритм дешифровки (побайтовый) - -Для каждого зашифрованного байта `encrypted[i]`, начиная с `i = 0`: - -``` -step 1: lo = hi ^ ((lo << 1) & 0xFF) // Сдвиг lo влево на 1, XOR с hi -step 2: decrypted[i] = lo ^ encrypted[i] // Расшифровка байта -step 3: hi = lo ^ ((hi >> 1) & 0xFF) // Сдвиг hi вправо на 1, XOR с lo -``` - -**Пример реализации:** - -```python -def decrypt_rs_entries(encrypted_data: bytes, seed: int) -> bytes: - lo = seed & 0xFF - hi = (seed >> 8) & 0xFF - result = bytearray(len(encrypted_data)) - for i in range(len(encrypted_data)): - lo = (hi ^ ((lo << 1) & 0xFF)) & 0xFF - result[i] = lo ^ encrypted_data[i] - hi = (lo ^ ((hi >> 1) & 0xFF)) & 0xFF - return bytes(result) -``` - -Этот же алгоритм используется для шифрования данных ресурсов с методом XOR (флаги 0x20, 0x60, 0xA0), но с другим начальным ключом из записи. - -### 2.4. Запись таблицы (32 байта, на диске, до дешифровки) - -После дешифровки каждая запись имеет следующую структуру: - -| Смещение | Размер | Тип | Описание | -| -------- | ------ | -------- | -------------------------------------------------------------- | -| 0 | 12 | char[12] | Имя ресурса (ASCII, обычно uppercase; строка читается до `\0`) | -| 12 | 4 | — | Зарезервировано (движком игнорируется) | -| 16 | 2 | int16 | **Флаги** (метод сжатия и атрибуты) | -| 18 | 2 | int16 | **`sort_to_original[i]` / XOR‑ключ** (см. ниже) | -| 20 | 4 | uint32 | **Размер распакованных данных** (`unpacked_size`) | -| 24 | 4 | uint32 | Смещение данных от начала файла (`data_offset`) | -| 28 | 4 | uint32 | Размер упакованных данных в байтах (`packed_size`) | - -#### Имена ресурсов - -- Поле `name[12]` копируется побайтно. Внутренне движок всегда имеет `\0` сразу после этих 12 байт (зарезервированные 4 байта в памяти принудительно обнуляются), поэтому имя **может быть длиной до 12 символов** даже без `\0` внутри `name[12]`. -- На практике имена обычно **uppercase ASCII**. `rsFind` приводит запрос к верхнему регистру (`_strupr`) и сравнивает побайтно. -- `rsFind` копирует имя запроса `strncpy(..., 16)` и принудительно ставит `\0` в `Destination[15]`, поэтому запрос длиннее 15 символов будет усечён. - -#### Поле `sort_to_original[i]` (смещение 18) - -Это **не “свойство записи”**, а элемент таблицы индексов, по которой `rsFind` делает двоичный поиск: - -- Таблица реализована “внутри записей”: значение берётся как `entry[i].sort_to_original` (где `i` — позиция двоичного поиска), а реальная запись для сравнения берётся как `entry[ sort_to_original[i] ]`. -- Тем же значением (младшие 16 бит) инициализируется XOR‑шифр данных для методов, где он используется (0x20/0x60/0xA0). Поэтому при упаковке/шифровании данных ключ должен совпадать с итоговым `sort_to_original[i]` (см. флаг 0xABBA в разделе 2.2). - -Поиск выполняется **двоичным поиском** по этой таблице, с фолбэком на **линейный поиск** если двоичный не нашёл (поведение `rsFind`). - -### 2.5. Поле флагов (смещение 16 записи) - -Биты поля флагов кодируют метод сжатия и дополнительные атрибуты: - -``` -Биты [8:5] (маска 0x1E0): Метод сжатия/шифрования -Бит [6] (маска 0x040): Флаг realloc (буфер декомпрессии может быть больше) -``` - -#### Методы сжатия (биты 8–5, маска 0x1E0) - -| Значение | Hex | Описание | -| -------- | ----- | --------------------------------------- | -| 0x000 | 0x00 | Без сжатия (копирование) | -| 0x020 | 0x20 | Только XOR-шифр | -| 0x040 | 0x40 | LZSS (простой вариант) | -| 0x060 | 0x60 | XOR-шифр + LZSS (простой вариант) | -| 0x080 | 0x80 | LZSS с адаптивным кодированием Хаффмана | -| 0x0A0 | 0xA0 | XOR-шифр + LZSS с Хаффманом | -| 0x100 | 0x100 | Deflate (аналог zlib/RFC 1951) | - -Примечание: `rsGetPackMethod()` возвращает `flags & 0x1C0` (без бита 0x20). Поэтому: - -- для 0x20 вернётся 0x00, -- для 0x60 вернётся 0x40, -- для 0xA0 вернётся 0x80. - -#### Бит 0x40 (выделение +0x12 и последующее `realloc`) - -Бит 0x40 проверяется отдельно (`flags & 0x40`). Если он установлен, выходной буфер выделяется с запасом `+0x12` (18 байт), а после распаковки вызывается `realloc` для усечения до точного `unpacked_size`. - -Важно: этот же бит входит в код методов 0x40/0x60, поэтому для них поведение “+0x12 и shrink” включено автоматически. - -### 2.6. Размеры данных - -В каждой записи на диске хранятся оба значения: - -- `unpacked_size` (смещение 20) — размер распакованных данных. -- `packed_size` (смещение 28) — размер упакованных данных (байт во входном потоке для выбранного метода). - -Для метода 0x00 (без сжатия) обычно `packed_size == unpacked_size`. - -`rsGetInfo` возвращает именно `unpacked_size` (то, сколько байт выдаст `rsLoad`). - -Практический нюанс для метода `0x100` (Deflate): в реальных игровых данных встречается запись, где `packed_size` указывает на диапазон до `EOF + 1`. Поток успешно декодируется и без последнего байта; это похоже на lookahead-поведение декодера. - -### 2.7. Опциональный трейлер медиа (6 байт) - -При открытии с флагом `a2 & 2`: - -| Смещение от конца | Размер | Тип | Описание | -| ----------------- | ------ | ------- | ----------------------- | -| −6 | 2 | char[2] | Сигнатура `AO` (0x4F41) | -| −4 | 4 | uint32 | Смещение медиа-оверлея | - -Если трейлер присутствует, все смещения данных в записях корректируются: `effective_offset = entry_offset + media_overlay_offset`. - ---- - -## Часть 3. Алгоритмы сжатия (формат RsLi) - -### 3.1. XOR-шифр данных (метод 0x20) - -Алгоритм идентичен XOR‑шифру таблицы записей (раздел 2.3), но начальный ключ берётся из `entry[i].sort_to_original` (смещение 18 записи, младшие 16 бит). - -Важно про размер входа: - -- В ветке **0x20** движок XOR‑ит ровно `unpacked_size` байт (и ожидает, что поток данных имеет ту же длину; на практике `packed_size == unpacked_size`). -- В ветках **0x60/0xA0** XOR применяется к **упакованному** потоку длиной `packed_size` перед декомпрессией. - -#### Инициализация - -``` -key16 = (uint16)entry.sort_to_original // int16 на диске по смещению 18 -lo = key16 & 0xFF -hi = (key16 >> 8) & 0xFF -``` - -#### Дешифровка (псевдокод) - -``` -for i in range(N): # N = unpacked_size (для 0x20) или packed_size (для 0x60/0xA0) - lo = (hi ^ ((lo << 1) & 0xFF)) & 0xFF - out[i] = in[i] ^ lo - hi = (lo ^ ((hi >> 1) & 0xFF)) & 0xFF -``` - -### 3.2. LZSS — простой вариант (метод 0x40) - -Классический алгоритм LZSS (Lempel-Ziv-Storer-Szymanski) с кольцевым буфером. - -#### Параметры - -| Параметр | Значение | -| ----------------------------- | ------------------ | -| Размер кольцевого буфера | 4096 байт (0x1000) | -| Начальная позиция записи | 4078 (0xFEE) | -| Начальное заполнение | 0x20 (пробел) | -| Минимальная длина совпадения | 3 | -| Максимальная длина совпадения | 18 (4 бита + 3) | - -#### Алгоритм декомпрессии - -``` -Инициализация: - ring_buffer[0..4095] = 0x20 (заполнить пробелами) - ring_pos = 4078 - flags_byte = 0 - flags_bits_remaining = 0 - -Цикл (пока не заполнен выходной буфер И не исчерпан входной): - - 1. Если flags_bits_remaining == 0: - - Прочитать 1 байт из входного потока → flags_byte - - flags_bits_remaining = 8 - - Декодировать как: - - Старший бит устанавливается в 0x7F (маркер) - - Оставшиеся 7 бит — флаги текущей группы - - Реально в коде: control_word = (flags_byte) | (0x7F << 8) - Каждый бит проверяется сдвигом вправо. - - 2. Проверить младший бит control_word: - - Если бит = 1 (литерал): - - Прочитать 1 байт из входного потока → byte - - ring_buffer[ring_pos] = byte - - ring_pos = (ring_pos + 1) & 0xFFF - - Записать byte в выходной буфер - - Если бит = 0 (ссылка): - - Прочитать 2 байта: low_byte, high_byte - - offset = low_byte | ((high_byte & 0xF0) << 4) // 12 бит - - length = (high_byte & 0x0F) + 3 // 4 бита + 3 - - Скопировать length байт из ring_buffer[offset...]: - для j от 0 до length-1: - byte = ring_buffer[(offset + j) & 0xFFF] - ring_buffer[ring_pos] = byte - ring_pos = (ring_pos + 1) & 0xFFF - записать byte в выходной буфер - - 3. Сдвинуть control_word вправо на 1 бит - 4. flags_bits_remaining -= 1 -``` - -#### Подробная раскладка пары ссылки (2 байта) - -``` -Байт 0 (low): OOOOOOOO (биты [7:0] смещения) -Байт 1 (high): OOOOLLLL O = биты [11:8] смещения, L = длина − 3 - -offset = low | ((high & 0xF0) << 4) // Диапазон: 0–4095 -length = (high & 0x0F) + 3 // Диапазон: 3–18 -``` - -### 3.3. LZSS с адаптивным кодированием Хаффмана (метод 0x80) - -Расширенный вариант LZSS, где литералы и длины совпадений кодируются с помощью адаптивного дерева Хаффмана. - -#### Параметры - -| Параметр | Значение | -| -------------------------------- | ------------------------------ | -| Размер кольцевого буфера | 4096 байт | -| Начальная позиция записи | **4036** (0xFC4) | -| Начальное заполнение | 0x20 (пробел) | -| Количество листовых узлов дерева | 314 | -| Символы литералов | 0–255 (байты) | -| Символы длин | 256–313 (длина = символ − 253) | -| Начальная длина | 3 (при символе 256) | -| Максимальная длина | 60 (при символе 313) | - -#### Дерево Хаффмана - -Дерево строится как **адаптивное** (dynamic, self-adjusting): - -- **627 узлов**: 314 листовых + 313 внутренних. -- Все листья изначально имеют **вес 1**. -- Корень дерева — узел с индексом 0 (в массиве `parent`). -- После декодирования каждого символа дерево **обновляется** (функция `sub_1001B0AE`): вес узла инкрементируется, и при нарушении порядка узлы **переставляются** для поддержания свойства. -- При достижении суммарного веса **0x8000 (32768)** — все веса **делятся на 2** (с округлением вверх) и дерево полностью перестраивается. - -#### Кодирование позиции - -Позиция в кольцевом буфере кодируется с помощью **d-кода** (таблица дистанций): - -- 8 бит позиции ищутся в таблице `d_code[256]`, определяя базовое значение и количество дополнительных битов. -- Из потока считываются дополнительные биты, которые объединяются с базовым значением. -- Финальная позиция: `pos = (ring_pos − 1 − decoded_position) & 0xFFF` - -**Таблицы инициализации** (d-коды): - -``` -Таблица базовых значений — byte_100371D0[6]: - { 0x01, 0x03, 0x08, 0x0C, 0x18, 0x10 } - -Таблица дополнительных битов — byte_100371D6[6]: - { 0x20, 0x30, 0x40, 0x30, 0x30, 0x10 } -``` - -#### Алгоритм декомпрессии (высокоуровневый) - -``` -Инициализация: - ring_buffer[0..4095] = 0x20 - ring_pos = 4036 - Инициализировать дерево Хаффмана (314 листьев, все веса = 1) - Инициализировать таблицы d-кодов - -Цикл: - 1. Декодировать символ из потока по дереву Хаффмана: - - Начать с корня - - Читать биты, спускаться по дереву (0 = левый, 1 = правый) - - Пока не достигнут лист → символ = лист − 627 - - 2. Обновить дерево Хаффмана для декодированного символа - - 3. Если символ < 256 (литерал): - - ring_buffer[ring_pos] = символ - - ring_pos = (ring_pos + 1) & 0xFFF - - Записать символ в выходной буфер - - 4. Если символ >= 256 (ссылка): - - length = символ − 253 - - Декодировать позицию через d-код: - a) Прочитать 8 бит из потока - b) Найти d-код и дополнительные биты по таблице - c) Прочитать дополнительные биты - d) position = (ring_pos − 1 − full_position) & 0xFFF - - Скопировать length байт из ring_buffer[position...] - - 5. Если выходной буфер заполнен → завершить -``` - -### 3.4. XOR + LZSS (методы 0x60 и 0xA0) - -Комбинированный метод: сначала XOR-дешифровка, затем LZSS-декомпрессия. - -#### Алгоритм - -1. Выделить временный буфер размером `compressed_size` (поле из записи, смещение 28). -2. Дешифровать сжатые данные XOR-шифром (раздел 3.1) с ключом из записи во временный буфер. -3. Применить LZSS-декомпрессию (простую или с Хаффманом, в зависимости от конкретного метода) из временного буфера в выходной. -4. Освободить временный буфер. - -- **0x60** — XOR + простой LZSS (раздел 3.2) -- **0xA0** — XOR + LZSS с Хаффманом (раздел 3.3) - -#### Начальное состояние XOR для данных - -При комбинированном методе seed берётся из поля по смещению 20 записи (4-байтный). Однако ключ обрабатывается как 16-битный: `lo = seed & 0xFF`, `hi = (seed >> 8) & 0xFF`. - -### 3.5. Deflate (метод 0x100) - -Полноценная реализация алгоритма **Deflate** (RFC 1951) с блочной структурой. - -#### Общая структура - -Данные состоят из последовательности блоков. Каждый блок начинается с: - -- **1 бит** — `is_final`: признак последнего блока -- **2 бита** — `block_type`: тип блока - -#### Типы блоков - -| block_type | Описание | Функция | -| ---------- | --------------------------- | ---------------- | -| 0 | Без сжатия (stored) | `sub_1001A750` | -| 1 | Фиксированные коды Хаффмана | `sub_1001A8C0` | -| 2 | Динамические коды Хаффмана | `sub_1001AA30` | -| 3 | Зарезервировано (ошибка) | Возвращает код 2 | - -#### Блок типа 0 (stored) - -1. Отбросить оставшиеся биты до границы байта (выравнивание). -2. Прочитать 16 бит — `LEN` (длина блока). -3. Прочитать 16 бит — `NLEN` (дополнение длины, `NLEN == ~LEN & 0xFFFF`). -4. Проверить: `LEN == (uint16)(~NLEN)`. При несовпадении — ошибка. -5. Скопировать `LEN` байт из входного потока в выходной. - -Декомпрессор использует внутренний буфер размером **32768 байт** (0x8000). При заполнении — промежуточная запись результата. - -#### Блок типа 1 (фиксированные коды) - -Стандартные коды Deflate: - -- Литералы/длины: 288 кодов - - 0–143: 8-битные коды - - 144–255: 9-битные коды - - 256–279: 7-битные коды - - 280–287: 8-битные коды -- Дистанции: 30 кодов, все 5-битные - -Используются предопределённые таблицы длин и дистанций (`unk_100370AC`, `unk_1003712C` и соответствующие экстра-биты). - -#### Блок типа 2 (динамические коды) - -1. Прочитать 5 бит → `HLIT` (количество литералов/длин − 257). Диапазон: 257–286. -2. Прочитать 5 бит → `HDIST` (количество дистанций − 1). Диапазон: 1–30. -3. Прочитать 4 бита → `HCLEN` (количество кодов длин − 4). Диапазон: 4–19. -4. Прочитать `HCLEN` × 3 бит — длины кодов для алфавита длин. -5. Построить дерево Хаффмана для алфавита длин (19 символов). -6. С помощью этого дерева декодировать длины кодов для литералов/длин и дистанций. -7. Построить два дерева Хаффмана: для литералов/длин и для дистанций. -8. Декодировать данные. - -**Порядок кодов длин** (стандартный Deflate): - -``` -{ 16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15 } -``` - -Хранится в `dword_10037060`. - -#### Валидации - -- `HLIT + 257 <= 286` (max 0x11E) -- `HDIST + 1 <= 30` (max 0x1E) -- При нарушении — возвращается ошибка 1. - -### 3.6. Метод 0x00 (без сжатия) - -Данные копируются «как есть» напрямую из файла. Вызывается через указатель на функцию `dword_1003A1B8` (фактически `memcpy` или аналог). - ---- - -## Часть 4. Внутренние структуры в памяти - -### 4.1. Внутренняя структура NRes-архива (opened, 0x68 байт = 104) - -```c -struct NResArchive { // Размер: 0x68 (104 байта) - void* vtable; // +0: Указатель на таблицу виртуальных методов - int32_t entry_count; // +4: Количество записей - void* mapped_base; // +8: Базовый адрес mapped view - void* directory_ptr; // +12: Указатель на каталог записей в памяти - char* filename; // +16: Путь к файлу (_strdup) - int32_t ref_count; // +20: Счётчик ссылок - uint32_t last_release_time; // +24: timeGetTime() при последнем Release - // +28..+91: Для raw-режима — встроенная запись (единственный File entry) - NResArchive* next; // +92: Следующий архив в связном списке - uint8_t is_writable; // +100: Файл открыт для записи - uint8_t is_cacheable; // +101: Не выгружать при refcount = 0 -}; -``` - -### 4.2. Внутренняя структура RsLi-архива (56 + 64 × N байт) - -```c -struct RsLibHeader { // 56 байт (14 DWORD) - uint32_t magic; // +0: 'RsLi' (0x694C7352) - int32_t entry_count; // +4: Количество записей - uint32_t media_offset; // +8: Смещение медиа-оверлея - uint32_t reserved_0C; // +12: 0 - HANDLE file_handle_2; // +16: -1 (дополнительный хэндл) - uint32_t reserved_14; // +20: 0 - uint32_t reserved_18; // +24: — - uint32_t reserved_1C; // +28: 0 - HANDLE mapping_handle_2; // +32: -1 - uint32_t reserved_24; // +36: 0 - uint32_t flag_28; // +40: (flags >> 7) & 1 - HANDLE file_handle; // +44: Хэндл файла - HANDLE mapping_handle; // +48: Хэндл файлового маппинга - void* mapped_view; // +52: Указатель на mapped view -}; -// Далее следуют entry_count записей по 64 байта каждая -``` - -#### Внутренняя запись RsLi (64 байта) - -```c -struct RsLibEntry { // 64 байта (16 DWORD) - char name[16]; // +0: Имя (12 из файла + 4 нуля) - int32_t flags; // +16: Флаги (sign-extended из int16) - int32_t sort_index; // +20: sort_to_original[i] (таблица индексов / XOR‑ключ) - uint32_t uncompressed_size; // +24: Размер несжатых данных (из поля 20 записи) - void* data_ptr; // +28: Указатель на данные в mapped view - uint32_t compressed_size; // +32: Размер сжатых данных (из поля 28 записи) - uint32_t reserved_24; // +36: 0 - uint32_t reserved_28; // +40: 0 - uint32_t reserved_2C; // +44: 0 - void* loaded_data; // +48: Указатель на декомпрессированные данные - // +52..+63: дополнительные поля -}; -``` - ---- - -## Часть 5. Экспортируемые API-функции - -### 5.1. NRes API - -| Функция | Описание | -| ------------------------------ | ------------------------------------------------------------------------- | -| `niOpenResFile(path)` | Открыть NRes-архив (только чтение), эквивалент `niOpenResFileEx(path, 0)` | -| `niOpenResFileEx(path, flags)` | Открыть NRes-архив с флагами | -| `niOpenResInMem(ptr, size)` | Открыть NRes-архив из памяти | -| `niCreateResFile(path)` | Создать/открыть NRes-архив для записи | - -### 5.2. RsLi API - -| Функция | Описание | -| ------------------------------- | -------------------------------------------------------- | -| `rsOpenLib(path, flags)` | Открыть RsLi-библиотеку | -| `rsCloseLib(lib)` | Закрыть библиотеку | -| `rsLibNum(lib)` | Получить количество записей | -| `rsFind(lib, name)` | Найти запись по имени (→ индекс или −1) | -| `rsLoad(lib, index)` | Загрузить и декомпрессировать ресурс | -| `rsLoadFast(lib, index, flags)` | Быстрая загрузка (без декомпрессии если возможно) | -| `rsLoadPacked(lib, index)` | Загрузить в «упакованном» виде (отложенная декомпрессия) | -| `rsLoadByName(lib, name)` | `rsFind` + `rsLoad` | -| `rsGetInfo(lib, index, out)` | Получить имя и размер ресурса | -| `rsGetPackMethod(lib, index)` | Получить метод сжатия (`flags & 0x1C0`) | -| `ngiUnpack(packed)` | Декомпрессировать ранее загруженный упакованный ресурс | -| `ngiAlloc(size)` | Выделить память (с обработкой ошибок) | -| `ngiFree(ptr)` | Освободить память | -| `ngiGetMemSize(ptr)` | Получить размер выделенного блока | - ---- - -## Часть 6. Контрольные заметки для реализации - -### 6.1. Кодировки и регистр - -- **NRes**: имена хранятся **как есть** (case-insensitive при поиске через `_strcmpi`). -- **RsLi**: имена хранятся в **верхнем регистре**. Перед поиском запрос приводится к верхнему регистру (`_strupr`). Сравнение — через `strcmp` (case-sensitive для уже uppercase строк). - -### 6.2. Порядок байт - -Все значения хранятся в **little-endian** порядке (платформа x86/Win32). - -### 6.3. Выравнивание - -- **NRes**: данные каждого ресурса выровнены по границе **8 байт** (0-padding между файлами). -- **RsLi**: выравнивание данных не описано в коде (данные идут подряд). - -### 6.4. Размер записей на диске - -- **NRes**: каталог — **64 байта** на запись, расположен в конце файла. -- **RsLi**: таблица — **32 байта** на запись (зашифрованная), расположена в начале файла (сразу после 32-байтного заголовка). - -### 6.5. Кэширование и memory mapping - -Оба формата используют Windows Memory-Mapped Files (`CreateFileMapping` + `MapViewOfFile`). NRes-архивы организованы в глобальный **связный список** (`dword_1003A66C`) со счётчиком ссылок и таймером неактивности (10 секунд = 0x2710 мс). При refcount == 0 и истечении таймера архив автоматически выгружается (если не установлен флаг `is_cacheable`). - -### 6.6. Размер seed XOR - -- **Заголовок RsLi**: seed — **4 байта** (DWORD) по смещению 20, но используются только младшие 2 байта (`lo = byte[0]`, `hi = byte[1]`). -- **Запись RsLi**: sort_to_original[i] — **2 байта** (int16) по смещению 18 записи. -- **Данные при комбинированном XOR+LZSS**: seed — **4 байта** (DWORD) из поля по смещению 20 записи, но опять используются только 2 байта. - -### 6.7. Эмпирическая проверка на данных игры - -- Найдено архивов по сигнатуре: **122** (`NRes`: 120, `RsLi`: 2). -- Выполнен полный roundtrip `unpack -> pack -> byte-compare`: **122/122** архивов совпали побайтно. -- Для `RsLi` в проверенном наборе встретились методы: `0x040` и `0x100`. - -Подтверждённые нюансы: - -- Для LZSS (метод `0x040`) рабочая раскладка нибблов в ссылке: `OOOO LLLL`, а не `LLLL OOOO`. -- Для Deflate (метод `0x100`) возможен случай `packed_size == фактический_конец + 1` на последней записи файла. diff --git a/docs/specs/runtime-pipeline.md b/docs/specs/runtime-pipeline.md deleted file mode 100644 index 7021c82..0000000 --- a/docs/specs/runtime-pipeline.md +++ /dev/null @@ -1,123 +0,0 @@ -# Runtime pipeline - -Документ фиксирует runtime-поведение движка: кто кого вызывает в кадре, как проходят рендер, коллизия и подключение эффектов. - ---- - -## 1.15. Алгоритм рендера модели (реконструкция) - -``` -Вход: model, instanceTransform, cameraFrustum - -1. Определить current_lod ∈ {0, 1, 2} (по дистанции до камеры / настройкам). - -2. Для каждого node (nodeIndex = 0 .. nodeCount−1): - a. Вычислить nodeTransform = instanceTransform × nodeLocalTransform - - b. slotIndex = nodeTable[nodeIndex].slotMatrix[current_lod][group=0] - если slotIndex == 0xFFFF → пропустить узел - - c. slot = slotTable[slotIndex] - - d. // Frustum culling: - transformedAABB = transform(slot.aabb, nodeTransform) - если transformedAABB вне cameraFrustum → пропустить - - // Альтернативно по сфере: - transformedCenter = nodeTransform × slot.sphereCenter - scaledRadius = slot.sphereRadius × max(scaleX, scaleY, scaleZ) - если сфера вне frustum → пропустить - - e. Для i = 0 .. slot.batchCount − 1: - batch = batchTable[slot.batchStart + i] - - // Фильтрация по batchFlags (если нужна) - - // Установить материал: - setMaterial(batch.materialIndex) - - // Установить transform: - setWorldMatrix(nodeTransform) - - // Нарисовать: - DrawIndexedPrimitive( - baseVertex = batch.baseVertex, - indexStart = batch.indexStart, - indexCount = batch.indexCount, - primitiveType = TRIANGLE_LIST - ) -``` - ---- - -## 1.16. Алгоритм обхода треугольников (коллизия / пикинг) - -``` -Вход: model, nodeIndex, lod, group, filterMask, callback - -1. slotIndex = nodeTable[nodeIndex].slotMatrix[lod][group] - если slotIndex == 0xFFFF → выход - -2. slot = slotTable[slotIndex] - triDescIndex = slot.triStart - -3. Для каждого batch в диапазоне [slot.batchStart .. slot.batchStart + slot.batchCount − 1]: - batch = batchTable[batchIndex] - triCount = batch.indexCount / 3 // округление: (indexCount + 2) / 3 - - Для t = 0 .. triCount − 1: - triDesc = triDescTable[triDescIndex] - - // Фильтрация: - если (triDesc.triFlags & filterMask) → пропустить - - // Получить индексы вершин: - idx0 = indexBuffer[batch.indexStart + t*3 + 0] + batch.baseVertex - idx1 = indexBuffer[batch.indexStart + t*3 + 1] + batch.baseVertex - idx2 = indexBuffer[batch.indexStart + t*3 + 2] + batch.baseVertex - - // Получить позиции: - p0 = positions[idx0] - p1 = positions[idx1] - p2 = positions[idx2] - - callback(triDesc, idx0, idx1, idx2, p0, p1, p2) - - triDescIndex += 1 -``` - ---- - - ---- - -## 3.1. Архитектурный обзор - -Подсистема эффектов реализована в `Effect.dll` и интегрирована в рендер через `Terrain.dll`. - -### Экспорты Effect.dll - -| Функция | Описание | -|----------------------|--------------------------------------------------------| -| `CreateFxManager` | Создать менеджер эффектов (3 параметра: int, int, int) | -| `InitializeSettings` | Инициализировать настройки эффектов | - -`CreateFxManager` возвращает объект‑менеджер, который регистрируется в движке и управляет всеми эффектами. - -### Телеметрия из Terrain.dll - -Terrain.dll содержит отладочную статистику рендера: - -``` -"Rendered meshes : %d" -"Rendered primitives : %d" -"Rendered faces : %d" -"Rendered particles/batches : %d/%d" -``` - -Из этого следует: - -- Частицы рендерятся **батчами** (группами). -- Статистика частиц отделена от статистики мешей. -- Частицы интегрированы в общий 3D‑рендер‑пайплайн. - diff --git a/docs/specs/sound.md b/docs/specs/sound.md deleted file mode 100644 index da2a6ee..0000000 --- a/docs/specs/sound.md +++ /dev/null @@ -1,5 +0,0 @@ -# Sound system - -Документ описывает аудиоподсистему: форматы звуковых ресурсов, воспроизведение эффектов и голосов, а также интеграцию со звуковым API. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга звуковых модулей движка. diff --git a/docs/specs/terrain-map-loading.md b/docs/specs/terrain-map-loading.md deleted file mode 100644 index 0fb6e1f..0000000 --- a/docs/specs/terrain-map-loading.md +++ /dev/null @@ -1,32 +0,0 @@ -# Terrain + map loading - -Документ описывает подсистему ландшафта и привязку terrain-данных к миру. - ---- - -## 4.1. Обзор - -`Terrain.dll` отвечает за рендер ландшафта (terrain), включая: - -- Рендер мешей ландшафта (`"Rendered meshes"`, `"Rendered primitives"`, `"Rendered faces"`). -- Рендер частиц (`"Rendered particles/batches"`). -- Создание текстур (`"CTexture::CTexture()"` — конструктор текстуры). -- Микротекстуры (`"Unable to find microtexture mapping"`). - -## 4.2. Текстуры ландшафта - -В Terrain.dll присутствует конструктор текстуры `CTexture::CTexture()` со следующими проверками: - -- Валидация размера текстуры (`"Unsupported texture size"`). -- Создание D3D‑текстуры (`"Unable to create texture"`). - -Ландшафт использует **микротекстуры** (micro‑texture mapping chunks) — маленькие повторяющиеся текстуры, тайлящиеся по поверхности. - -## 4.3. Защита от пустых примитивов - -Terrain.dll содержит проверки: - -- `"Rendering empty primitive!"` — перед первым вызовом отрисовки. -- `"Rendering empty primitive2!"` — перед вторым вызовом отрисовки. - -Это подтверждает многопроходный рендер (как минимум 2 прохода для ландшафта). diff --git a/docs/specs/ui.md b/docs/specs/ui.md deleted file mode 100644 index 9d71dfd..0000000 --- a/docs/specs/ui.md +++ /dev/null @@ -1,5 +0,0 @@ -# UI system - -Документ описывает интерфейсную подсистему: ресурсы UI, шрифты, minimap, layout и обработку пользовательского ввода в интерфейсе. - -> Статус: в работе. Спецификация будет дополняться по мере реверс-инжиниринга UI-компонентов движка. diff --git a/libnres/Cargo.toml b/libnres/Cargo.toml new file mode 100644 index 0000000..99539e7 --- /dev/null +++ b/libnres/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "libnres" +version = "0.1.4" +description = "Library for NRes files" +authors = ["Valentin Popov <valentin@popov.link>"] +homepage = "https://git.popov.link/valentineus/fparkan" +repository = "https://git.popov.link/valentineus/fparkan.git" +license = "GPL-2.0" +edition = "2021" +keywords = ["gamedev", "library", "nres"] + +[dependencies] +byteorder = "1.4" +log = "0.4" +miette = "7.0" +thiserror = "2.0" diff --git a/libnres/README.md b/libnres/README.md new file mode 100644 index 0000000..065bd40 --- /dev/null +++ b/libnres/README.md @@ -0,0 +1,25 @@ +# Library for NRes files (Deprecated) + +Library for viewing and retrieving game resources of the game **"Parkan: Iron Strategy"**. +All versions of the game are supported: Demo, IS, IS: Part 1, IS: Part 2. +Supports files with `lib`, `trf`, `rlb` extensions. + +The files `gamefont.rlb` and `sprites.lib` are not supported. +This files have an unknown signature. + +## Example + +Example of extracting game resources: + +```rust +fn main() { + let file = std::fs::File::open("./voices.lib").unwrap(); + // Extracting the list of files + let list = libnres::reader::get_list(&file).unwrap(); + + for element in list { + // Extracting the contents of the file + let data = libnres::reader::get_file(&file, &element).unwrap(); + } +} +``` diff --git a/libnres/src/converter.rs b/libnres/src/converter.rs new file mode 100644 index 0000000..bbf0535 --- /dev/null +++ b/libnres/src/converter.rs @@ -0,0 +1,33 @@ +use crate::error::ConverterError; + +/// Method for converting u32 to u64. +pub fn u32_to_u64(value: u32) -> Result<u64, ConverterError> { + match u64::try_from(value) { + Err(error) => Err(ConverterError::Infallible(error)), + Ok(result) => Ok(result), + } +} + +/// Method for converting u32 to usize. +pub fn u32_to_usize(value: u32) -> Result<usize, ConverterError> { + match usize::try_from(value) { + Err(error) => Err(ConverterError::TryFromIntError(error)), + Ok(result) => Ok(result), + } +} + +/// Method for converting u64 to u32. +pub fn u64_to_u32(value: u64) -> Result<u32, ConverterError> { + match u32::try_from(value) { + Err(error) => Err(ConverterError::TryFromIntError(error)), + Ok(result) => Ok(result), + } +} + +/// Method for converting usize to u32. +pub fn usize_to_u32(value: usize) -> Result<u32, ConverterError> { + match u32::try_from(value) { + Err(error) => Err(ConverterError::TryFromIntError(error)), + Ok(result) => Ok(result), + } +} diff --git a/libnres/src/error.rs b/libnres/src/error.rs new file mode 100644 index 0000000..440ab06 --- /dev/null +++ b/libnres/src/error.rs @@ -0,0 +1,45 @@ +extern crate miette; +extern crate thiserror; + +use miette::Diagnostic; +use thiserror::Error; + +#[derive(Error, Diagnostic, Debug)] +pub enum ConverterError { + #[error("error converting an value")] + #[diagnostic(code(libnres::infallible))] + Infallible(#[from] std::convert::Infallible), + + #[error("error converting an value")] + #[diagnostic(code(libnres::try_from_int_error))] + TryFromIntError(#[from] std::num::TryFromIntError), +} + +#[derive(Error, Diagnostic, Debug)] +pub enum ReaderError { + #[error(transparent)] + #[diagnostic(code(libnres::convert_error))] + ConvertValue(#[from] ConverterError), + + #[error("incorrect header format")] + #[diagnostic(code(libnres::list_type_error))] + IncorrectHeader, + + #[error("incorrect file size (expected {expected:?} bytes, received {received:?} bytes)")] + #[diagnostic(code(libnres::file_size_error))] + IncorrectSizeFile { expected: u32, received: u32 }, + + #[error( + "incorrect size of the file list (not a multiple of {expected:?}, received {received:?})" + )] + #[diagnostic(code(libnres::list_size_error))] + IncorrectSizeList { expected: u32, received: u32 }, + + #[error("resource file reading error")] + #[diagnostic(code(libnres::io_error))] + ReadFile(#[from] std::io::Error), + + #[error("file is too small (must be at least {expected:?} bytes, received {received:?} byte)")] + #[diagnostic(code(libnres::file_size_error))] + SmallFile { expected: u32, received: u32 }, +} diff --git a/libnres/src/lib.rs b/libnres/src/lib.rs new file mode 100644 index 0000000..40c0b32 --- /dev/null +++ b/libnres/src/lib.rs @@ -0,0 +1,24 @@ +/// First constant value of the NRes file ("NRes" characters in numeric) +pub const FILE_TYPE_1: u32 = 1936020046; +/// Second constant value of the NRes file +pub const FILE_TYPE_2: u32 = 256; +/// Size of the element item (in bytes) +pub const LIST_ELEMENT_SIZE: u32 = 64; +/// Minimum allowed file size (in bytes) +pub const MINIMUM_FILE_SIZE: u32 = 16; + +static DEBUG: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); + +mod converter; +mod error; +pub mod reader; + +/// Get debug status value +pub fn get_debug() -> bool { + DEBUG.load(std::sync::atomic::Ordering::Relaxed) +} + +/// Change debug status value +pub fn set_debug(value: bool) { + DEBUG.store(value, std::sync::atomic::Ordering::Relaxed) +} diff --git a/libnres/src/reader.rs b/libnres/src/reader.rs new file mode 100644 index 0000000..2a450ee --- /dev/null +++ b/libnres/src/reader.rs @@ -0,0 +1,227 @@ +use std::io::{Read, Seek}; + +use byteorder::ByteOrder; + +use crate::error::ReaderError; +use crate::{converter, FILE_TYPE_1, FILE_TYPE_2, LIST_ELEMENT_SIZE, MINIMUM_FILE_SIZE}; + +#[derive(Debug)] +pub struct ListElement { + /// Unknown parameter + _unknown0: i32, + /// Unknown parameter + _unknown1: i32, + /// Unknown parameter + _unknown2: i32, + /// File extension + pub extension: String, + /// Identifier or sequence number + pub index: u32, + /// File name + pub name: String, + /// Position in the file + pub position: u32, + /// File size (in bytes) + pub size: u32, +} + +impl ListElement { + /// Get full name of the file + pub fn get_filename(&self) -> String { + format!("{}.{}", self.name, self.extension) + } +} + +#[derive(Debug)] +pub struct FileHeader { + /// File size + size: u32, + /// Number of files + total: u32, + /// First constant value + type1: u32, + /// Second constant value + type2: u32, +} + +/// Get a packed file data +pub fn get_file(file: &std::fs::File, element: &ListElement) -> Result<Vec<u8>, ReaderError> { + let size = get_file_size(file)?; + check_file_size(size)?; + + let header = get_file_header(file)?; + check_file_header(&header, size)?; + + let data = get_element_data(file, element)?; + Ok(data) +} + +/// Get a list of packed files +pub fn get_list(file: &std::fs::File) -> Result<Vec<ListElement>, ReaderError> { + let mut list: Vec<ListElement> = Vec::new(); + + let size = get_file_size(file)?; + check_file_size(size)?; + + let header = get_file_header(file)?; + check_file_header(&header, size)?; + + get_file_list(file, &header, &mut list)?; + + Ok(list) +} + +fn check_file_header(header: &FileHeader, size: u32) -> Result<(), ReaderError> { + if header.type1 != FILE_TYPE_1 || header.type2 != FILE_TYPE_2 { + return Err(ReaderError::IncorrectHeader); + } + + if header.size != size { + return Err(ReaderError::IncorrectSizeFile { + expected: size, + received: header.size, + }); + } + + Ok(()) +} + +fn check_file_size(size: u32) -> Result<(), ReaderError> { + if size < MINIMUM_FILE_SIZE { + return Err(ReaderError::SmallFile { + expected: MINIMUM_FILE_SIZE, + received: size, + }); + } + + Ok(()) +} + +fn get_element_data(file: &std::fs::File, element: &ListElement) -> Result<Vec<u8>, ReaderError> { + let position = converter::u32_to_u64(element.position)?; + let size = converter::u32_to_usize(element.size)?; + + let mut reader = std::io::BufReader::new(file); + let mut buffer = vec![0u8; size]; + + if let Err(error) = reader.seek(std::io::SeekFrom::Start(position)) { + return Err(ReaderError::ReadFile(error)); + }; + + if let Err(error) = reader.read_exact(&mut buffer) { + return Err(ReaderError::ReadFile(error)); + }; + + Ok(buffer) +} + +fn get_element_position(index: u32) -> Result<(usize, usize), ReaderError> { + let from = converter::u32_to_usize(index * LIST_ELEMENT_SIZE)?; + let to = converter::u32_to_usize((index * LIST_ELEMENT_SIZE) + LIST_ELEMENT_SIZE)?; + Ok((from, to)) +} + +fn get_file_header(file: &std::fs::File) -> Result<FileHeader, ReaderError> { + let mut reader = std::io::BufReader::new(file); + let mut buffer = vec![0u8; MINIMUM_FILE_SIZE as usize]; + + if let Err(error) = reader.seek(std::io::SeekFrom::Start(0)) { + return Err(ReaderError::ReadFile(error)); + }; + + if let Err(error) = reader.read_exact(&mut buffer) { + return Err(ReaderError::ReadFile(error)); + }; + + let header = FileHeader { + size: byteorder::LittleEndian::read_u32(&buffer[12..16]), + total: byteorder::LittleEndian::read_u32(&buffer[8..12]), + type1: byteorder::LittleEndian::read_u32(&buffer[0..4]), + type2: byteorder::LittleEndian::read_u32(&buffer[4..8]), + }; + + buffer.clear(); + Ok(header) +} + +fn get_file_list( + file: &std::fs::File, + header: &FileHeader, + list: &mut Vec<ListElement>, +) -> Result<(), ReaderError> { + let (start_position, list_size) = get_list_position(header)?; + let mut reader = std::io::BufReader::new(file); + let mut buffer = vec![0u8; list_size]; + + if let Err(error) = reader.seek(std::io::SeekFrom::Start(start_position)) { + return Err(ReaderError::ReadFile(error)); + }; + + if let Err(error) = reader.read_exact(&mut buffer) { + return Err(ReaderError::ReadFile(error)); + } + + let buffer_size = converter::usize_to_u32(buffer.len())?; + + if buffer_size % LIST_ELEMENT_SIZE != 0 { + return Err(ReaderError::IncorrectSizeList { + expected: LIST_ELEMENT_SIZE, + received: buffer_size, + }); + } + + for i in 0..(buffer_size / LIST_ELEMENT_SIZE) { + let (from, to) = get_element_position(i)?; + let chunk: &[u8] = &buffer[from..to]; + + let element = get_list_element(chunk)?; + list.push(element); + } + + buffer.clear(); + Ok(()) +} + +fn get_file_size(file: &std::fs::File) -> Result<u32, ReaderError> { + let metadata = match file.metadata() { + Err(error) => return Err(ReaderError::ReadFile(error)), + Ok(value) => value, + }; + + let result = converter::u64_to_u32(metadata.len())?; + Ok(result) +} + +fn get_list_element(buffer: &[u8]) -> Result<ListElement, ReaderError> { + let index = byteorder::LittleEndian::read_u32(&buffer[60..64]); + let position = byteorder::LittleEndian::read_u32(&buffer[56..60]); + let size = byteorder::LittleEndian::read_u32(&buffer[12..16]); + let unknown0 = byteorder::LittleEndian::read_i32(&buffer[4..8]); + let unknown1 = byteorder::LittleEndian::read_i32(&buffer[8..12]); + let unknown2 = byteorder::LittleEndian::read_i32(&buffer[16..20]); + + let extension = String::from_utf8_lossy(&buffer[0..4]) + .trim_matches(char::from(0)) + .to_string(); + + let name = String::from_utf8_lossy(&buffer[20..56]) + .trim_matches(char::from(0)) + .to_string(); + + Ok(ListElement { + _unknown0: unknown0, + _unknown1: unknown1, + _unknown2: unknown2, + extension, + index, + name, + position, + size, + }) +} + +fn get_list_position(header: &FileHeader) -> Result<(u64, usize), ReaderError> { + let position = converter::u32_to_u64(header.size - (header.total * LIST_ELEMENT_SIZE))?; + let size = converter::u32_to_usize(header.total * LIST_ELEMENT_SIZE)?; + Ok((position, size)) +} @@ -10,37 +10,15 @@ repo_name: valentineus/fparkan repo_url: https://github.com/valentineus/fparkan # Copyright -copyright: Copyright © 2023 — 2026 Valentin Popov +copyright: Copyright © 2023 — 2024 Valentin Popov # Configuration theme: name: material - language: ru + language: en palette: scheme: slate -# Navigation -nav: - - Home: index.md - - Specs: - - 3D implementation notes: specs/msh-notes.md - - AI system: specs/ai.md - - ArealMap: specs/arealmap.md - - Behavior system: specs/behavior.md - - Control system: specs/control.md - - FXID: specs/fxid.md - - Materials + Texm: specs/materials-texm.md - - Missions: specs/missions.md - - MSH animation: specs/msh-animation.md - - MSH core: specs/msh-core.md - - Network system: specs/network.md - - NRes / RsLi: specs/nres.md - - Runtime pipeline: specs/runtime-pipeline.md - - Sound system: specs/sound.md - - Terrain + map loading: specs/terrain-map-loading.md - - UI system: specs/ui.md - - Форматы 3D‑ресурсов (обзор): specs/msh.md - # Additional configuration extra: social: diff --git a/nres-cli/Cargo.toml b/nres-cli/Cargo.toml new file mode 100644 index 0000000..a6d863c --- /dev/null +++ b/nres-cli/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "nres-cli" +version = "0.2.3" +description = "Console tool for NRes files" +authors = ["Valentin Popov <valentin@popov.link>"] +homepage = "https://git.popov.link/valentineus/fparkan" +repository = "https://git.popov.link/valentineus/fparkan.git" +license = "GPL-2.0" +edition = "2021" +keywords = ["cli", "gamedev", "nres"] + +[dependencies] +byteorder = "1.4" +clap = { version = "4.2", features = ["derive"] } +console = "0.15" +dialoguer = { version = "0.11", features = ["completion"] } +indicatif = "0.17" +libnres = { version = "0.1", path = "../libnres" } +miette = { version = "7.0", features = ["fancy"] } +tempdir = "0.3" diff --git a/nres-cli/README.md b/nres-cli/README.md new file mode 100644 index 0000000..65a6602 --- /dev/null +++ b/nres-cli/README.md @@ -0,0 +1,6 @@ +# Console tool for NRes files (Deprecated) + +## Commands + +- `extract` - Extract game resources from a "NRes" file. +- `ls` - Get a list of files in a "NRes" file. diff --git a/nres-cli/src/main.rs b/nres-cli/src/main.rs new file mode 100644 index 0000000..85086cb --- /dev/null +++ b/nres-cli/src/main.rs @@ -0,0 +1,198 @@ +extern crate core; +extern crate libnres; + +use std::io::Write; + +use clap::{Parser, Subcommand}; +use miette::{IntoDiagnostic, Result}; + +#[derive(Parser, Debug)] +#[command(name = "NRes CLI")] +#[command(about, author, version, long_about = None)] +struct Cli { + #[command(subcommand)] + command: Commands, +} + +#[derive(Subcommand, Debug)] +enum Commands { + /// Check if the "NRes" file can be extract + Check { + /// "NRes" file + file: String, + }, + /// Print debugging information on the "NRes" file + #[command(arg_required_else_help = true)] + Debug { + /// "NRes" file + file: String, + /// Filter results by file name + #[arg(long)] + name: Option<String>, + }, + /// Extract files or a file from the "NRes" file + #[command(arg_required_else_help = true)] + Extract { + /// "NRes" file + file: String, + /// Overwrite files + #[arg(short, long, default_value_t = false, value_name = "TRUE|FALSE")] + force: bool, + /// Outbound directory + #[arg(short, long, value_name = "DIR")] + out: String, + }, + /// Print a list of files in the "NRes" file + #[command(arg_required_else_help = true)] + Ls { + /// "NRes" file + file: String, + }, +} + +pub fn main() -> Result<()> { + let stdout = console::Term::stdout(); + let cli = Cli::parse(); + + match cli.command { + Commands::Check { file } => command_check(stdout, file)?, + Commands::Debug { file, name } => command_debug(stdout, file, name)?, + Commands::Extract { file, force, out } => command_extract(stdout, file, out, force)?, + Commands::Ls { file } => command_ls(stdout, file)?, + } + + Ok(()) +} + +fn command_check(_stdout: console::Term, file: String) -> Result<()> { + let file = std::fs::File::open(file).into_diagnostic()?; + let list = libnres::reader::get_list(&file).into_diagnostic()?; + let tmp = tempdir::TempDir::new("nres").into_diagnostic()?; + let bar = indicatif::ProgressBar::new(list.len() as u64); + + bar.set_style(get_bar_style()?); + + for element in list { + bar.set_message(element.get_filename()); + + let path = tmp.path().join(element.get_filename()); + let mut output = std::fs::File::create(path).into_diagnostic()?; + let mut buffer = libnres::reader::get_file(&file, &element).into_diagnostic()?; + + output.write_all(&buffer).into_diagnostic()?; + buffer.clear(); + bar.inc(1); + } + + bar.finish(); + + Ok(()) +} + +fn command_debug(stdout: console::Term, file: String, name: Option<String>) -> Result<()> { + let file = std::fs::File::open(file).into_diagnostic()?; + let mut list = libnres::reader::get_list(&file).into_diagnostic()?; + + let mut total_files_size: u32 = 0; + let mut total_files_gap: u32 = 0; + let mut total_files: u32 = 0; + + for (index, item) in list.iter().enumerate() { + total_files_size += item.size; + total_files += 1; + let mut gap = 0; + + if index > 1 { + let previous_item = &list[index - 1]; + gap = item.position - (previous_item.position + previous_item.size); + } + + total_files_gap += gap; + } + + if let Some(name) = name { + list.retain(|item| item.name.contains(&name)); + }; + + for (index, item) in list.iter().enumerate() { + let mut gap = 0; + + if index > 1 { + let previous_item = &list[index - 1]; + gap = item.position - (previous_item.position + previous_item.size); + } + + let text = format!("Index: {};\nGap: {};\nItem: {:#?};\n", index, gap, item); + stdout.write_line(&text).into_diagnostic()?; + } + + let text = format!( + "Total files: {};\nTotal files gap: {} (bytes);\nTotal files size: {} (bytes);", + total_files, total_files_gap, total_files_size + ); + + stdout.write_line(&text).into_diagnostic()?; + + Ok(()) +} + +fn command_extract(_stdout: console::Term, file: String, out: String, force: bool) -> Result<()> { + let file = std::fs::File::open(file).into_diagnostic()?; + let list = libnres::reader::get_list(&file).into_diagnostic()?; + let bar = indicatif::ProgressBar::new(list.len() as u64); + + bar.set_style(get_bar_style()?); + + for element in list { + bar.set_message(element.get_filename()); + + let path = format!("{}/{}", out, element.get_filename()); + + if !force && is_exist_file(&path) { + let message = format!("File \"{}\" exists. Overwrite it?", path); + + if !dialoguer::Confirm::new() + .with_prompt(message) + .interact() + .into_diagnostic()? + { + continue; + } + } + + let mut output = std::fs::File::create(path).into_diagnostic()?; + let mut buffer = libnres::reader::get_file(&file, &element).into_diagnostic()?; + + output.write_all(&buffer).into_diagnostic()?; + buffer.clear(); + bar.inc(1); + } + + bar.finish(); + + Ok(()) +} + +fn command_ls(stdout: console::Term, file: String) -> Result<()> { + let file = std::fs::File::open(file).into_diagnostic()?; + let list = libnres::reader::get_list(&file).into_diagnostic()?; + + for element in list { + stdout.write_line(&element.name).into_diagnostic()?; + } + + Ok(()) +} + +fn get_bar_style() -> Result<indicatif::ProgressStyle> { + Ok( + indicatif::ProgressStyle::with_template("[{bar:32}] {pos:>7}/{len:7} {msg}") + .into_diagnostic()? + .progress_chars("=>-"), + ) +} + +fn is_exist_file(path: &String) -> bool { + let metadata = std::path::Path::new(path); + metadata.exists() +} diff --git a/packer/Cargo.toml b/packer/Cargo.toml new file mode 100644 index 0000000..cbf418c --- /dev/null +++ b/packer/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "packer" +version = "0.1.0" +edition = "2021" + +[dependencies] +byteorder = "1.4.3" +serde = { version = "1.0.160", features = ["derive"] } +serde_json = "1.0.96" diff --git a/packer/README.md b/packer/README.md new file mode 100644 index 0000000..9edb048 --- /dev/null +++ b/packer/README.md @@ -0,0 +1,27 @@ +# NRes Game Resource Packer + +At the moment, this is a demonstration of the NRes game resource packing algorithm in action. +It packs 100% of the NRes game resources for the game "Parkan: Iron Strategy". +The hash sums of the resulting files match the original game files. + +__Attention!__ +This is a test version of the utility. It overwrites the specified final file without asking. + +## Building + +To build the tools, you need to run the following command in the root directory: + +```bash +cargo build --release +``` + +## Running + +You can run the utility with the following command: + +```bash +./target/release/packer /path/to/unpack /path/to/file.ex +``` + +- `/path/to/unpack`: This is the directory with the resources unpacked by the [unpacker](../unpacker) utility. +- `/path/to/file.ex`: This is the final file that will be created. diff --git a/packer/src/main.rs b/packer/src/main.rs new file mode 100644 index 0000000..a5526e3 --- /dev/null +++ b/packer/src/main.rs @@ -0,0 +1,175 @@ +use std::env; +use std::{ + fs::{self, File}, + io::{BufReader, Read}, +}; + +use byteorder::{ByteOrder, LittleEndian}; +use serde::{Deserialize, Serialize}; + +#[derive(Serialize, Deserialize, Debug)] +pub struct ImportListElement { + pub extension: String, + pub index: u32, + pub name: String, + pub unknown0: u32, + pub unknown1: u32, + pub unknown2: u32, +} + +#[derive(Debug)] +pub struct ListElement { + pub extension: String, + pub index: u32, + pub name: String, + pub position: u32, + pub size: u32, + pub unknown0: u32, + pub unknown1: u32, + pub unknown2: u32, +} + +fn main() { + let args: Vec<String> = env::args().collect(); + + let input = &args[1]; + let output = &args[2]; + + pack(String::from(input), String::from(output)); +} + +fn pack(input: String, output: String) { + // Загружаем индекс-файл + let index_file = format!("{}/{}", input, "index.json"); + let data = fs::read_to_string(index_file).unwrap(); + let list: Vec<ImportListElement> = serde_json::from_str(&data).unwrap(); + + // Общий буфер хранения файлов + let mut content_buffer: Vec<u8> = Vec::new(); + let mut list_buffer: Vec<u8> = Vec::new(); + + // Общее количество файлов + let total_files: u32 = list.len() as u32; + + for (index, item) in list.iter().enumerate() { + // Открываем дескриптор файла + let path = format!("{}/{}.{}", input, item.name, item.index); + let file = File::open(path).unwrap(); + let metadata = file.metadata().unwrap(); + + // Считываем файл в буфер + let mut reader = BufReader::new(file); + let mut file_buffer: Vec<u8> = Vec::new(); + reader.read_to_end(&mut file_buffer).unwrap(); + + // Выравнивание буфера + if index != 0 { + while content_buffer.len() % 8 != 0 { + content_buffer.push(0); + } + } + + // Получение позиции файла + let position = content_buffer.len() + 16; + + // Записываем файл в буфер + content_buffer.extend(file_buffer); + + // Формируем элемент + let element = ListElement { + extension: item.extension.to_string(), + index: item.index, + name: item.name.to_string(), + position: position as u32, + size: metadata.len() as u32, + unknown0: item.unknown0, + unknown1: item.unknown1, + unknown2: item.unknown2, + }; + + // Создаем буфер из элемента + let mut element_buffer: Vec<u8> = Vec::new(); + + // Пишем тип файла + let mut extension_buffer: [u8; 4] = [0; 4]; + let mut file_extension_buffer = element.extension.into_bytes(); + file_extension_buffer.resize(4, 0); + extension_buffer.copy_from_slice(&file_extension_buffer); + element_buffer.extend(extension_buffer); + + // Пишем неизвестное значение #1 + let mut unknown0_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut unknown0_buffer, element.unknown0); + element_buffer.extend(unknown0_buffer); + + // Пишем неизвестное значение #2 + let mut unknown1_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut unknown1_buffer, element.unknown1); + element_buffer.extend(unknown1_buffer); + + // Пишем размер файла + let mut file_size_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut file_size_buffer, element.size); + element_buffer.extend(file_size_buffer); + + // Пишем неизвестное значение #3 + let mut unknown2_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut unknown2_buffer, element.unknown2); + element_buffer.extend(unknown2_buffer); + + // Пишем название файла + let mut name_buffer: [u8; 36] = [0; 36]; + let mut file_name_buffer = element.name.into_bytes(); + file_name_buffer.resize(36, 0); + name_buffer.copy_from_slice(&file_name_buffer); + element_buffer.extend(name_buffer); + + // Пишем позицию файла + let mut position_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut position_buffer, element.position); + element_buffer.extend(position_buffer); + + // Пишем индекс файла + let mut index_buffer: [u8; 4] = [0; 4]; + LittleEndian::write_u32(&mut index_buffer, element.index); + element_buffer.extend(index_buffer); + + // Добавляем итоговый буфер в буфер элементов списка + list_buffer.extend(element_buffer); + } + + // Выравнивание буфера + while content_buffer.len() % 8 != 0 { + content_buffer.push(0); + } + + let mut header_buffer: Vec<u8> = Vec::new(); + + // Пишем первый тип файла + let mut header_type_1 = [0; 4]; + LittleEndian::write_u32(&mut header_type_1, 1936020046_u32); + header_buffer.extend(header_type_1); + + // Пишем второй тип файла + let mut header_type_2 = [0; 4]; + LittleEndian::write_u32(&mut header_type_2, 256_u32); + header_buffer.extend(header_type_2); + + // Пишем количество файлов + let mut header_total_files = [0; 4]; + LittleEndian::write_u32(&mut header_total_files, total_files); + header_buffer.extend(header_total_files); + + // Пишем общий размер файла + let mut header_total_size = [0; 4]; + let total_size: u32 = ((content_buffer.len() + 16) as u32) + (total_files * 64); + LittleEndian::write_u32(&mut header_total_size, total_size); + header_buffer.extend(header_total_size); + + let mut result_buffer: Vec<u8> = Vec::new(); + result_buffer.extend(header_buffer); + result_buffer.extend(content_buffer); + result_buffer.extend(list_buffer); + + fs::write(output, result_buffer).unwrap(); +} diff --git a/renovate.config.cjs b/renovate.config.cjs deleted file mode 100644 index 9d56531..0000000 --- a/renovate.config.cjs +++ /dev/null @@ -1,6 +0,0 @@ -module.exports = { - endpoint: "https://code.popov.link", - gitAuthor: "renovate[bot] <renovatebot@noreply.localhost>", - optimizeForDisabled: true, - platform: "gitea", -};
\ No newline at end of file diff --git a/testdata/nres/.gitignore b/testdata/nres/.gitignore deleted file mode 100644 index c96a04f..0000000 --- a/testdata/nres/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -* -!.gitignore
\ No newline at end of file diff --git a/testdata/rsli/.gitignore b/testdata/rsli/.gitignore deleted file mode 100644 index c96a04f..0000000 --- a/testdata/rsli/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -* -!.gitignore
\ No newline at end of file diff --git a/texture-decoder/Cargo.toml b/texture-decoder/Cargo.toml new file mode 100644 index 0000000..0d11da6 --- /dev/null +++ b/texture-decoder/Cargo.toml @@ -0,0 +1,8 @@ +[package] +name = "texture-decoder" +version = "0.1.0" +edition = "2021" + +[dependencies] +byteorder = "1.4.3" +image = "0.25.0" diff --git a/texture-decoder/README.md b/texture-decoder/README.md new file mode 100644 index 0000000..8fca059 --- /dev/null +++ b/texture-decoder/README.md @@ -0,0 +1,13 @@ +# Декодировщик текстур + +Сборка: + +```bash +cargo build --release +``` + +Запуск: + +```bash +./target/release/texture-decoder ./out/AIM_02.0 ./out/AIM_02.0.png +```
\ No newline at end of file diff --git a/texture-decoder/src/main.rs b/texture-decoder/src/main.rs new file mode 100644 index 0000000..26c7edd --- /dev/null +++ b/texture-decoder/src/main.rs @@ -0,0 +1,41 @@ +use std::io::Read; + +use byteorder::ReadBytesExt; +use image::Rgba; + +fn decode_texture(file_path: &str, output_path: &str) -> Result<(), std::io::Error> { + // Читаем файл + let mut file = std::fs::File::open(file_path)?; + let mut buffer: Vec<u8> = Vec::new(); + file.read_to_end(&mut buffer)?; + + // Декодируем метаданные + let mut cursor = std::io::Cursor::new(&buffer[4..]); + let img_width = cursor.read_u32::<byteorder::LittleEndian>()?; + let img_height = cursor.read_u32::<byteorder::LittleEndian>()?; + + // Пропустить оставшиеся байты метаданных + cursor.set_position(20); + + // Извлекаем данные изображения + let image_data = buffer[cursor.position() as usize..].to_vec(); + let img = + image::ImageBuffer::<Rgba<u8>, _>::from_raw(img_width, img_height, image_data.to_vec()) + .expect("Failed to decode image"); + + // Сохраняем изображение + img.save(output_path).unwrap(); + + Ok(()) +} + +fn main() { + let args: Vec<String> = std::env::args().collect(); + + let input = &args[1]; + let output = &args[2]; + + if let Err(err) = decode_texture(input, output) { + eprintln!("Error: {}", err) + } +} diff --git a/tools/README.md b/tools/README.md deleted file mode 100644 index 2418567..0000000 --- a/tools/README.md +++ /dev/null @@ -1,201 +0,0 @@ -# Инструменты в каталоге `tools` - -## `archive_roundtrip_validator.py` - -Скрипт предназначен для **валидации документации по форматам NRes и RsLi на реальных данных игры**. - -Что делает утилита: - -- находит архивы по сигнатуре заголовка (а не по расширению файла); -- распаковывает архивы в структуру `manifest.json + entries/*`; -- собирает архивы обратно из `manifest.json`; -- выполняет проверку `unpack -> repack -> byte-compare`; -- формирует отчёт о расхождениях со спецификацией. - -Скрипт не изменяет оригинальные файлы игры. Рабочие файлы создаются только в указанном `--workdir` (или во временной папке). - -## Поддерживаемые сигнатуры - -- `NRes` (`4E 52 65 73`) -- `RsLi` в файловом формате библиотеки: `NL 00 01` - -## Основные команды - -Сканирование архива по сигнатурам: - -```bash -python3 tools/archive_roundtrip_validator.py scan --input tmp/gamedata -``` - -Распаковка/упаковка одного NRes: - -```bash -python3 tools/archive_roundtrip_validator.py nres-unpack \ - --archive tmp/gamedata/sounds.lib \ - --output tmp/work/nres_sounds - -python3 tools/archive_roundtrip_validator.py nres-pack \ - --manifest tmp/work/nres_sounds/manifest.json \ - --output tmp/work/sounds.repacked.lib -``` - -Распаковка/упаковка одного RsLi: - -```bash -python3 tools/archive_roundtrip_validator.py rsli-unpack \ - --archive tmp/gamedata/sprites.lib \ - --output tmp/work/rsli_sprites - -python3 tools/archive_roundtrip_validator.py rsli-pack \ - --manifest tmp/work/rsli_sprites/manifest.json \ - --output tmp/work/sprites.repacked.lib -``` - -Полная валидация документации на всём наборе данных: - -```bash -python3 tools/archive_roundtrip_validator.py validate \ - --input tmp/gamedata \ - --workdir tmp/validation_work \ - --report tmp/validation_report.json \ - --fail-on-diff -``` - -## Формат распаковки - -Для каждого архива создаются: - -- `manifest.json` — все поля заголовка, записи, индексы, смещения, контрольные суммы; -- `entries/*.bin` — payload-файлы. - -Имена файлов в `entries` включают индекс записи, поэтому коллизии одинаковых имён внутри архива обрабатываются корректно. - -## `init_testdata.py` - -Скрипт инициализирует тестовые данные по сигнатурам архивов из спецификации: - -- `NRes` (`4E 52 65 73`); -- `RsLi` (`NL 00 01`). - -Что делает утилита: - -- рекурсивно сканирует все файлы в `--input`; -- копирует найденные `NRes` в `--output/nres/`; -- копирует найденные `RsLi` в `--output/rsli/`; -- сохраняет относительный путь исходного файла внутри целевого каталога; -- создаёт целевые каталоги автоматически, если их нет. - -Базовый запуск: - -```bash -python3 tools/init_testdata.py --input tmp/gamedata --output testdata -``` - -Если целевой файл уже существует, скрипт спрашивает подтверждение перезаписи (`yes/no/all/quit`). - -Для перезаписи без вопросов используйте `--force`: - -```bash -python3 tools/init_testdata.py --input tmp/gamedata --output testdata --force -``` - -Проверки надёжности: - -- `--input` должен существовать и быть каталогом; -- если `--output` указывает на существующий файл, скрипт завершится с ошибкой; -- если `--output` расположен внутри `--input`, каталог вывода исключается из сканирования; -- если `stdin` неинтерактивный и требуется перезапись, нужно явно указать `--force`. - -## `msh_doc_validator.py` - -Скрипт валидирует ключевые инварианты из документации `/Users/valentineus/Developer/personal/fparkan/docs/specs/msh.md` на реальных данных. - -Проверяемые группы: - -- модели `*.msh` (вложенные `NRes` в архивах `NRes`); -- текстуры `Texm` (`type_id = 0x6D786554`); -- эффекты `FXID` (`type_id = 0x44495846`). - -Что проверяет для моделей: - -- обязательные ресурсы (`Res1/2/3/6/13`) и известные опциональные (`Res4/5/7/8/10/15/16/18/19`); -- `size/attr1/attr3` и шаги структур по таблицам; -- диапазоны индексов, батчей и ссылок между таблицами; -- разбор `Res10` как `len + bytes + NUL` для каждого узла; -- матрицу слотов в `Res1` (LOD/group) и границы по `Res2/Res7/Res13/Res19`. - -Быстрый запуск: - -```bash -python3 tools/msh_doc_validator.py scan --input testdata/nres -python3 tools/msh_doc_validator.py validate --input testdata/nres --print-limit 20 -``` - -С отчётом в JSON: - -```bash -python3 tools/msh_doc_validator.py validate \ - --input testdata/nres \ - --report tmp/msh_validation_report.json \ - --fail-on-warnings -``` - -## `msh_preview_renderer.py` - -Примитивный программный рендерер моделей `*.msh` без внешних зависимостей. - -- вход: архив `NRes` (например `animals.rlb`) или прямой payload модели; -- выход: изображение `PPM` (`P6`); -- использует `Res3` (позиции), `Res6` (индексы), `Res13` (батчи), `Res1/Res2` (выбор слотов по `lod/group`). - -Показать доступные модели в архиве: - -```bash -python3 tools/msh_preview_renderer.py list-models --archive testdata/nres/animals.rlb -``` - -Сгенерировать тестовый рендер: - -```bash -python3 tools/msh_preview_renderer.py render \ - --archive testdata/nres/animals.rlb \ - --model A_L_01.msh \ - --output tmp/renders/A_L_01.ppm \ - --width 800 \ - --height 600 \ - --lod 0 \ - --group 0 \ - --wireframe -``` - -Ограничения: - -- инструмент предназначен для smoke-теста геометрии, а не для пиксельно-точного рендера движка; -- текстуры/материалы/эффектные проходы не эмулируются. - -## `msh_export_obj.py` - -Экспортирует геометрию `*.msh` в `Wavefront OBJ`, чтобы открыть модель в Blender/MeshLab. - -- вход: `NRes` архив (например `animals.rlb`) или прямой payload модели; -- выбор геометрии: через `Res1` slot matrix (`lod/group`) как в рендерере; -- опция `--all-batches` экспортирует все батчи, игнорируя slot matrix. - -Показать модели в архиве: - -```bash -python3 tools/msh_export_obj.py list-models --archive testdata/nres/animals.rlb -``` - -Экспорт в OBJ: - -```bash -python3 tools/msh_export_obj.py export \ - --archive testdata/nres/animals.rlb \ - --model A_L_01.msh \ - --output tmp/renders/A_L_01.obj \ - --lod 0 \ - --group 0 -``` - -Файл `OBJ` можно открыть напрямую в Blender (`File -> Import -> Wavefront (.obj)`). diff --git a/tools/archive_roundtrip_validator.py b/tools/archive_roundtrip_validator.py deleted file mode 100644 index 073fd9b..0000000 --- a/tools/archive_roundtrip_validator.py +++ /dev/null @@ -1,944 +0,0 @@ -#!/usr/bin/env python3 -""" -Roundtrip tools for NRes and RsLi archives. - -The script can: -1) scan archives by header signature (ignores file extensions), -2) unpack / pack NRes archives, -3) unpack / pack RsLi archives, -4) validate docs assumptions by full roundtrip and byte-to-byte comparison. -""" - -from __future__ import annotations - -import argparse -import hashlib -import json -import re -import shutil -import struct -import tempfile -import zlib -from pathlib import Path -from typing import Any - -MAGIC_NRES = b"NRes" -MAGIC_RSLI = b"NL\x00\x01" - - -class ArchiveFormatError(RuntimeError): - pass - - -def sha256_hex(data: bytes) -> str: - return hashlib.sha256(data).hexdigest() - - -def safe_component(value: str, fallback: str = "item", max_len: int = 80) -> str: - clean = re.sub(r"[^A-Za-z0-9._-]+", "_", value).strip("._-") - if not clean: - clean = fallback - return clean[:max_len] - - -def first_diff(a: bytes, b: bytes) -> tuple[int | None, str | None]: - if a == b: - return None, None - limit = min(len(a), len(b)) - for idx in range(limit): - if a[idx] != b[idx]: - return idx, f"{a[idx]:02x}!={b[idx]:02x}" - return limit, f"len {len(a)}!={len(b)}" - - -def load_json(path: Path) -> dict[str, Any]: - with path.open("r", encoding="utf-8") as handle: - return json.load(handle) - - -def dump_json(path: Path, payload: dict[str, Any]) -> None: - path.parent.mkdir(parents=True, exist_ok=True) - with path.open("w", encoding="utf-8") as handle: - json.dump(payload, handle, indent=2, ensure_ascii=False) - handle.write("\n") - - -def xor_stream(data: bytes, key16: int) -> bytes: - lo = key16 & 0xFF - hi = (key16 >> 8) & 0xFF - out = bytearray(len(data)) - for i, value in enumerate(data): - lo = (hi ^ ((lo << 1) & 0xFF)) & 0xFF - out[i] = value ^ lo - hi = (lo ^ ((hi >> 1) & 0xFF)) & 0xFF - return bytes(out) - - -def lzss_decompress_simple(data: bytes, expected_size: int) -> bytes: - ring = bytearray([0x20] * 0x1000) - ring_pos = 0xFEE - out = bytearray() - in_pos = 0 - control = 0 - bits_left = 0 - - while len(out) < expected_size and in_pos < len(data): - if bits_left == 0: - control = data[in_pos] - in_pos += 1 - bits_left = 8 - - if control & 1: - if in_pos >= len(data): - break - byte = data[in_pos] - in_pos += 1 - out.append(byte) - ring[ring_pos] = byte - ring_pos = (ring_pos + 1) & 0x0FFF - else: - if in_pos + 1 >= len(data): - break - low = data[in_pos] - high = data[in_pos + 1] - in_pos += 2 - # Real files indicate nibble layout opposite to common LZSS variant: - # high nibble extends offset, low nibble stores (length - 3). - offset = low | ((high & 0xF0) << 4) - length = (high & 0x0F) + 3 - for step in range(length): - byte = ring[(offset + step) & 0x0FFF] - out.append(byte) - ring[ring_pos] = byte - ring_pos = (ring_pos + 1) & 0x0FFF - if len(out) >= expected_size: - break - - control >>= 1 - bits_left -= 1 - - if len(out) != expected_size: - raise ArchiveFormatError( - f"LZSS size mismatch: expected {expected_size}, got {len(out)}" - ) - return bytes(out) - - -def decode_rsli_payload( - packed: bytes, method: int, sort_to_original: int, unpacked_size: int -) -> bytes: - key16 = sort_to_original & 0xFFFF - - if method == 0x000: - out = packed - elif method == 0x020: - if len(packed) < unpacked_size: - raise ArchiveFormatError( - f"method 0x20 packed too short: {len(packed)} < {unpacked_size}" - ) - out = xor_stream(packed[:unpacked_size], key16) - elif method == 0x040: - out = lzss_decompress_simple(packed, unpacked_size) - elif method == 0x060: - out = lzss_decompress_simple(xor_stream(packed, key16), unpacked_size) - elif method == 0x100: - try: - out = zlib.decompress(packed, -15) - except zlib.error: - out = zlib.decompress(packed) - else: - raise ArchiveFormatError(f"unsupported RsLi method: 0x{method:03X}") - - if len(out) != unpacked_size: - raise ArchiveFormatError( - f"unpacked_size mismatch: expected {unpacked_size}, got {len(out)}" - ) - return out - - -def detect_archive_type(path: Path) -> str | None: - try: - with path.open("rb") as handle: - magic = handle.read(4) - except OSError: - return None - - if magic == MAGIC_NRES: - return "nres" - if magic == MAGIC_RSLI: - return "rsli" - return None - - -def scan_archives(root: Path) -> list[dict[str, Any]]: - found: list[dict[str, Any]] = [] - for path in sorted(root.rglob("*")): - if not path.is_file(): - continue - archive_type = detect_archive_type(path) - if not archive_type: - continue - found.append( - { - "path": str(path), - "relative_path": str(path.relative_to(root)), - "type": archive_type, - "size": path.stat().st_size, - } - ) - return found - - -def parse_nres(data: bytes, source: str = "<memory>") -> dict[str, Any]: - if len(data) < 16: - raise ArchiveFormatError(f"{source}: NRes too short ({len(data)} bytes)") - - magic, version, entry_count, total_size = struct.unpack_from("<4sIII", data, 0) - if magic != MAGIC_NRES: - raise ArchiveFormatError(f"{source}: invalid NRes magic") - - issues: list[str] = [] - if total_size != len(data): - issues.append( - f"header.total_size={total_size} != actual_size={len(data)} (spec 1.2)" - ) - if version != 0x100: - issues.append(f"version=0x{version:08X} != 0x00000100 (spec 1.2)") - - directory_offset = total_size - entry_count * 64 - if directory_offset < 16 or directory_offset > len(data): - raise ArchiveFormatError( - f"{source}: invalid directory offset {directory_offset} for entry_count={entry_count}" - ) - if directory_offset + entry_count * 64 != len(data): - issues.append( - "directory_offset + entry_count*64 != file_size (spec 1.3)" - ) - - entries: list[dict[str, Any]] = [] - for index in range(entry_count): - offset = directory_offset + index * 64 - if offset + 64 > len(data): - raise ArchiveFormatError(f"{source}: truncated directory entry {index}") - - ( - type_id, - attr1, - attr2, - size, - attr3, - name_raw, - data_offset, - sort_index, - ) = struct.unpack_from("<IIIII36sII", data, offset) - name_bytes = name_raw.split(b"\x00", 1)[0] - name = name_bytes.decode("latin1", errors="replace") - entries.append( - { - "index": index, - "type_id": type_id, - "attr1": attr1, - "attr2": attr2, - "size": size, - "attr3": attr3, - "name": name, - "name_bytes_hex": name_bytes.hex(), - "name_raw_hex": name_raw.hex(), - "data_offset": data_offset, - "sort_index": sort_index, - } - ) - - # Spec checks. - expected_sort = sorted( - range(entry_count), - key=lambda idx: bytes.fromhex(entries[idx]["name_bytes_hex"]).lower(), - ) - current_sort = [item["sort_index"] for item in entries] - if current_sort != expected_sort: - issues.append( - "sort_index table does not match case-insensitive name order (spec 1.4)" - ) - - data_regions = sorted( - ( - item["index"], - item["data_offset"], - item["size"], - ) - for item in entries - ) - for idx, data_offset, size in data_regions: - if data_offset % 8 != 0: - issues.append(f"entry {idx}: data_offset={data_offset} not aligned to 8 (spec 1.5)") - if data_offset < 16 or data_offset + size > directory_offset: - issues.append( - f"entry {idx}: data range [{data_offset}, {data_offset + size}) out of data area (spec 1.3)" - ) - for i in range(len(data_regions) - 1): - _, start, size = data_regions[i] - _, next_start, _ = data_regions[i + 1] - if start + size > next_start: - issues.append( - f"entry overlap at data_offset={start}, next={next_start}" - ) - padding = data[start + size : next_start] - if any(padding): - issues.append( - f"non-zero padding after data block at offset={start + size} (spec 1.5)" - ) - - return { - "format": "NRes", - "header": { - "magic": "NRes", - "version": version, - "entry_count": entry_count, - "total_size": total_size, - "directory_offset": directory_offset, - }, - "entries": entries, - "issues": issues, - } - - -def build_nres_name_field(entry: dict[str, Any]) -> bytes: - if "name_bytes_hex" in entry: - raw = bytes.fromhex(entry["name_bytes_hex"]) - else: - raw = entry.get("name", "").encode("latin1", errors="replace") - raw = raw[:35] - return raw + b"\x00" * (36 - len(raw)) - - -def unpack_nres_file(archive_path: Path, out_dir: Path, source_root: Path | None = None) -> dict[str, Any]: - data = archive_path.read_bytes() - parsed = parse_nres(data, source=str(archive_path)) - - out_dir.mkdir(parents=True, exist_ok=True) - entries_dir = out_dir / "entries" - entries_dir.mkdir(parents=True, exist_ok=True) - - manifest: dict[str, Any] = { - "format": "NRes", - "source_path": str(archive_path), - "source_relative_path": str(archive_path.relative_to(source_root)) if source_root else str(archive_path), - "header": parsed["header"], - "entries": [], - "issues": parsed["issues"], - "source_sha256": sha256_hex(data), - } - - for entry in parsed["entries"]: - begin = entry["data_offset"] - end = begin + entry["size"] - if begin < 0 or end > len(data): - raise ArchiveFormatError( - f"{archive_path}: entry {entry['index']} data range outside file" - ) - payload = data[begin:end] - base = safe_component(entry["name"], fallback=f"entry_{entry['index']:05d}") - file_name = ( - f"{entry['index']:05d}__{base}" - f"__t{entry['type_id']:08X}_a1{entry['attr1']:08X}_a2{entry['attr2']:08X}.bin" - ) - (entries_dir / file_name).write_bytes(payload) - - manifest_entry = dict(entry) - manifest_entry["data_file"] = f"entries/{file_name}" - manifest_entry["sha256"] = sha256_hex(payload) - manifest["entries"].append(manifest_entry) - - dump_json(out_dir / "manifest.json", manifest) - return manifest - - -def pack_nres_manifest(manifest_path: Path, out_file: Path) -> bytes: - manifest = load_json(manifest_path) - if manifest.get("format") != "NRes": - raise ArchiveFormatError(f"{manifest_path}: not an NRes manifest") - - entries = manifest["entries"] - count = len(entries) - version = int(manifest.get("header", {}).get("version", 0x100)) - - out = bytearray(b"\x00" * 16) - data_offsets: list[int] = [] - data_sizes: list[int] = [] - - for entry in entries: - payload_path = manifest_path.parent / entry["data_file"] - payload = payload_path.read_bytes() - offset = len(out) - out.extend(payload) - padding = (-len(out)) % 8 - if padding: - out.extend(b"\x00" * padding) - data_offsets.append(offset) - data_sizes.append(len(payload)) - - directory_offset = len(out) - expected_sort = sorted( - range(count), - key=lambda idx: bytes.fromhex(entries[idx].get("name_bytes_hex", "")).lower(), - ) - - for index, entry in enumerate(entries): - name_field = build_nres_name_field(entry) - out.extend( - struct.pack( - "<IIIII36sII", - int(entry["type_id"]), - int(entry["attr1"]), - int(entry["attr2"]), - data_sizes[index], - int(entry["attr3"]), - name_field, - data_offsets[index], - expected_sort[index], - ) - ) - - total_size = len(out) - struct.pack_into("<4sIII", out, 0, MAGIC_NRES, version, count, total_size) - - out_file.parent.mkdir(parents=True, exist_ok=True) - out_file.write_bytes(out) - return bytes(out) - - -def parse_rsli(data: bytes, source: str = "<memory>") -> dict[str, Any]: - if len(data) < 32: - raise ArchiveFormatError(f"{source}: RsLi too short ({len(data)} bytes)") - if data[:4] != MAGIC_RSLI: - raise ArchiveFormatError(f"{source}: invalid RsLi magic") - - issues: list[str] = [] - reserved_zero = data[2] - version = data[3] - entry_count = struct.unpack_from("<h", data, 4)[0] - presorted_flag = struct.unpack_from("<H", data, 14)[0] - seed = struct.unpack_from("<I", data, 20)[0] - - if reserved_zero != 0: - issues.append(f"header[2]={reserved_zero} != 0 (spec 2.2)") - if version != 1: - issues.append(f"version={version} != 1 (spec 2.2)") - if entry_count < 0: - raise ArchiveFormatError(f"{source}: negative entry_count={entry_count}") - - table_offset = 32 - table_size = entry_count * 32 - if table_offset + table_size > len(data): - raise ArchiveFormatError( - f"{source}: encrypted table out of file bounds ({table_offset}+{table_size}>{len(data)})" - ) - - table_encrypted = data[table_offset : table_offset + table_size] - table_plain = xor_stream(table_encrypted, seed & 0xFFFF) - - trailer: dict[str, Any] = {"present": False} - overlay_offset = 0 - if len(data) >= 6 and data[-6:-4] == b"AO": - overlay_offset = struct.unpack_from("<I", data, len(data) - 4)[0] - trailer = { - "present": True, - "signature": "AO", - "overlay_offset": overlay_offset, - "raw_hex": data[-6:].hex(), - } - - entries: list[dict[str, Any]] = [] - sort_values: list[int] = [] - for index in range(entry_count): - row = table_plain[index * 32 : (index + 1) * 32] - name_raw = row[0:12] - reserved4 = row[12:16] - flags_signed, sort_to_original = struct.unpack_from("<hh", row, 16) - unpacked_size, data_offset, packed_size = struct.unpack_from("<III", row, 20) - method = flags_signed & 0x1E0 - name = name_raw.split(b"\x00", 1)[0].decode("latin1", errors="replace") - effective_offset = data_offset + overlay_offset - entries.append( - { - "index": index, - "name": name, - "name_raw_hex": name_raw.hex(), - "reserved_raw_hex": reserved4.hex(), - "flags_signed": flags_signed, - "flags_u16": flags_signed & 0xFFFF, - "method": method, - "sort_to_original": sort_to_original, - "unpacked_size": unpacked_size, - "data_offset": data_offset, - "effective_data_offset": effective_offset, - "packed_size": packed_size, - } - ) - sort_values.append(sort_to_original) - - if effective_offset < 0: - issues.append(f"entry {index}: negative effective_data_offset={effective_offset}") - elif effective_offset + packed_size > len(data): - end = effective_offset + packed_size - if method == 0x100 and end == len(data) + 1: - issues.append( - f"entry {index}: deflate packed_size reaches EOF+1 ({end}); " - "observed in game data, likely decoder lookahead byte" - ) - else: - issues.append( - f"entry {index}: packed range [{effective_offset}, {end}) out of file" - ) - - if presorted_flag == 0xABBA: - if sorted(sort_values) != list(range(entry_count)): - issues.append( - "presorted flag is 0xABBA but sort_to_original is not a permutation [0..N-1] (spec 2.2/2.4)" - ) - - return { - "format": "RsLi", - "header_raw_hex": data[:32].hex(), - "header": { - "magic": "NL\\x00\\x01", - "entry_count": entry_count, - "seed": seed, - "presorted_flag": presorted_flag, - }, - "entries": entries, - "issues": issues, - "trailer": trailer, - } - - -def unpack_rsli_file(archive_path: Path, out_dir: Path, source_root: Path | None = None) -> dict[str, Any]: - data = archive_path.read_bytes() - parsed = parse_rsli(data, source=str(archive_path)) - - out_dir.mkdir(parents=True, exist_ok=True) - entries_dir = out_dir / "entries" - entries_dir.mkdir(parents=True, exist_ok=True) - - manifest: dict[str, Any] = { - "format": "RsLi", - "source_path": str(archive_path), - "source_relative_path": str(archive_path.relative_to(source_root)) if source_root else str(archive_path), - "source_size": len(data), - "header_raw_hex": parsed["header_raw_hex"], - "header": parsed["header"], - "entries": [], - "issues": list(parsed["issues"]), - "trailer": parsed["trailer"], - "source_sha256": sha256_hex(data), - } - - for entry in parsed["entries"]: - begin = int(entry["effective_data_offset"]) - end = begin + int(entry["packed_size"]) - packed = data[begin:end] - base = safe_component(entry["name"], fallback=f"entry_{entry['index']:05d}") - packed_name = f"{entry['index']:05d}__{base}__packed.bin" - (entries_dir / packed_name).write_bytes(packed) - - manifest_entry = dict(entry) - manifest_entry["packed_file"] = f"entries/{packed_name}" - manifest_entry["packed_file_size"] = len(packed) - manifest_entry["packed_sha256"] = sha256_hex(packed) - - try: - unpacked = decode_rsli_payload( - packed=packed, - method=int(entry["method"]), - sort_to_original=int(entry["sort_to_original"]), - unpacked_size=int(entry["unpacked_size"]), - ) - unpacked_name = f"{entry['index']:05d}__{base}__unpacked.bin" - (entries_dir / unpacked_name).write_bytes(unpacked) - manifest_entry["unpacked_file"] = f"entries/{unpacked_name}" - manifest_entry["unpacked_sha256"] = sha256_hex(unpacked) - except ArchiveFormatError as exc: - manifest_entry["unpack_error"] = str(exc) - manifest["issues"].append( - f"entry {entry['index']}: cannot decode method 0x{entry['method']:03X}: {exc}" - ) - - manifest["entries"].append(manifest_entry) - - dump_json(out_dir / "manifest.json", manifest) - return manifest - - -def _pack_i16(value: int) -> int: - if not (-32768 <= int(value) <= 32767): - raise ArchiveFormatError(f"int16 overflow: {value}") - return int(value) - - -def pack_rsli_manifest(manifest_path: Path, out_file: Path) -> bytes: - manifest = load_json(manifest_path) - if manifest.get("format") != "RsLi": - raise ArchiveFormatError(f"{manifest_path}: not an RsLi manifest") - - entries = manifest["entries"] - count = len(entries) - - header_raw = bytes.fromhex(manifest["header_raw_hex"]) - if len(header_raw) != 32: - raise ArchiveFormatError(f"{manifest_path}: header_raw_hex must be 32 bytes") - header = bytearray(header_raw) - header[:4] = MAGIC_RSLI - struct.pack_into("<h", header, 4, count) - seed = int(manifest["header"]["seed"]) - struct.pack_into("<I", header, 20, seed) - - rows = bytearray() - packed_chunks: list[tuple[dict[str, Any], bytes]] = [] - - for entry in entries: - packed_path = manifest_path.parent / entry["packed_file"] - packed = packed_path.read_bytes() - declared_size = int(entry["packed_size"]) - if len(packed) > declared_size: - raise ArchiveFormatError( - f"{packed_path}: packed size {len(packed)} > manifest packed_size {declared_size}" - ) - - data_offset = int(entry["data_offset"]) - packed_chunks.append((entry, packed)) - - row = bytearray(32) - name_raw = bytes.fromhex(entry["name_raw_hex"]) - reserved_raw = bytes.fromhex(entry["reserved_raw_hex"]) - if len(name_raw) != 12 or len(reserved_raw) != 4: - raise ArchiveFormatError( - f"entry {entry['index']}: invalid name/reserved raw length" - ) - row[0:12] = name_raw - row[12:16] = reserved_raw - struct.pack_into( - "<hhIII", - row, - 16, - _pack_i16(int(entry["flags_signed"])), - _pack_i16(int(entry["sort_to_original"])), - int(entry["unpacked_size"]), - data_offset, - declared_size, - ) - rows.extend(row) - - encrypted_table = xor_stream(bytes(rows), seed & 0xFFFF) - trailer = manifest.get("trailer", {}) - trailer_raw = b"" - if trailer.get("present"): - raw_hex = trailer.get("raw_hex", "") - trailer_raw = bytes.fromhex(raw_hex) - if len(trailer_raw) != 6: - raise ArchiveFormatError("trailer raw length must be 6 bytes") - - source_size = manifest.get("source_size") - table_end = 32 + count * 32 - if source_size is not None: - pre_trailer_size = int(source_size) - len(trailer_raw) - if pre_trailer_size < table_end: - raise ArchiveFormatError( - f"invalid source_size={source_size}: smaller than header+table" - ) - else: - pre_trailer_size = table_end - for entry, packed in packed_chunks: - pre_trailer_size = max( - pre_trailer_size, int(entry["data_offset"]) + len(packed) - ) - - out = bytearray(pre_trailer_size) - out[0:32] = header - out[32:table_end] = encrypted_table - occupied = bytearray(pre_trailer_size) - occupied[0:table_end] = b"\x01" * table_end - - for entry, packed in packed_chunks: - base_offset = int(entry["data_offset"]) - for index, byte in enumerate(packed): - pos = base_offset + index - if pos >= pre_trailer_size: - raise ArchiveFormatError( - f"entry {entry['index']}: data write at {pos} beyond output size {pre_trailer_size}" - ) - if occupied[pos] and out[pos] != byte: - raise ArchiveFormatError( - f"entry {entry['index']}: overlapping packed data conflict at offset {pos}" - ) - out[pos] = byte - occupied[pos] = 1 - - out.extend(trailer_raw) - if source_size is not None and len(out) != int(source_size): - raise ArchiveFormatError( - f"packed size {len(out)} != source_size {source_size} from manifest" - ) - - out_file.parent.mkdir(parents=True, exist_ok=True) - out_file.write_bytes(out) - return bytes(out) - - -def cmd_scan(args: argparse.Namespace) -> int: - root = Path(args.input).resolve() - archives = scan_archives(root) - if args.json: - print(json.dumps(archives, ensure_ascii=False, indent=2)) - else: - print(f"Found {len(archives)} archive(s) in {root}") - for item in archives: - print(f"{item['type']:4} {item['size']:10d} {item['relative_path']}") - return 0 - - -def cmd_nres_unpack(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - out_dir = Path(args.output).resolve() - manifest = unpack_nres_file(archive_path, out_dir) - print(f"NRes unpacked: {archive_path}") - print(f"Manifest: {out_dir / 'manifest.json'}") - print(f"Entries : {len(manifest['entries'])}") - if manifest["issues"]: - print("Issues:") - for issue in manifest["issues"]: - print(f"- {issue}") - return 0 - - -def cmd_nres_pack(args: argparse.Namespace) -> int: - manifest_path = Path(args.manifest).resolve() - out_file = Path(args.output).resolve() - packed = pack_nres_manifest(manifest_path, out_file) - print(f"NRes packed: {out_file} ({len(packed)} bytes, sha256={sha256_hex(packed)})") - return 0 - - -def cmd_rsli_unpack(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - out_dir = Path(args.output).resolve() - manifest = unpack_rsli_file(archive_path, out_dir) - print(f"RsLi unpacked: {archive_path}") - print(f"Manifest: {out_dir / 'manifest.json'}") - print(f"Entries : {len(manifest['entries'])}") - if manifest["issues"]: - print("Issues:") - for issue in manifest["issues"]: - print(f"- {issue}") - return 0 - - -def cmd_rsli_pack(args: argparse.Namespace) -> int: - manifest_path = Path(args.manifest).resolve() - out_file = Path(args.output).resolve() - packed = pack_rsli_manifest(manifest_path, out_file) - print(f"RsLi packed: {out_file} ({len(packed)} bytes, sha256={sha256_hex(packed)})") - return 0 - - -def cmd_validate(args: argparse.Namespace) -> int: - input_root = Path(args.input).resolve() - archives = scan_archives(input_root) - - temp_created = False - if args.workdir: - workdir = Path(args.workdir).resolve() - workdir.mkdir(parents=True, exist_ok=True) - else: - workdir = Path(tempfile.mkdtemp(prefix="nres-rsli-validate-")) - temp_created = True - - report: dict[str, Any] = { - "input_root": str(input_root), - "workdir": str(workdir), - "archives_total": len(archives), - "results": [], - "summary": {}, - } - - failures = 0 - try: - for idx, item in enumerate(archives): - rel = item["relative_path"] - archive_path = input_root / rel - marker = f"{idx:04d}_{safe_component(rel, fallback='archive')}" - unpack_dir = workdir / "unpacked" / marker - repacked_file = workdir / "repacked" / f"{marker}.bin" - try: - if item["type"] == "nres": - manifest = unpack_nres_file(archive_path, unpack_dir, source_root=input_root) - repacked = pack_nres_manifest(unpack_dir / "manifest.json", repacked_file) - elif item["type"] == "rsli": - manifest = unpack_rsli_file(archive_path, unpack_dir, source_root=input_root) - repacked = pack_rsli_manifest(unpack_dir / "manifest.json", repacked_file) - else: - continue - - original = archive_path.read_bytes() - match = original == repacked - diff_offset, diff_desc = first_diff(original, repacked) - issues = list(manifest.get("issues", [])) - result = { - "relative_path": rel, - "type": item["type"], - "size_original": len(original), - "size_repacked": len(repacked), - "sha256_original": sha256_hex(original), - "sha256_repacked": sha256_hex(repacked), - "match": match, - "first_diff_offset": diff_offset, - "first_diff": diff_desc, - "issues": issues, - "entries": len(manifest.get("entries", [])), - "error": None, - } - except Exception as exc: # pylint: disable=broad-except - result = { - "relative_path": rel, - "type": item["type"], - "size_original": item["size"], - "size_repacked": None, - "sha256_original": None, - "sha256_repacked": None, - "match": False, - "first_diff_offset": None, - "first_diff": None, - "issues": [f"processing error: {exc}"], - "entries": None, - "error": str(exc), - } - - report["results"].append(result) - - if not result["match"]: - failures += 1 - if result["issues"] and args.fail_on_issues: - failures += 1 - - matches = sum(1 for row in report["results"] if row["match"]) - mismatches = len(report["results"]) - matches - nres_count = sum(1 for row in report["results"] if row["type"] == "nres") - rsli_count = sum(1 for row in report["results"] if row["type"] == "rsli") - issues_total = sum(len(row["issues"]) for row in report["results"]) - report["summary"] = { - "nres_count": nres_count, - "rsli_count": rsli_count, - "matches": matches, - "mismatches": mismatches, - "issues_total": issues_total, - } - - if args.report: - dump_json(Path(args.report).resolve(), report) - - print(f"Input root : {input_root}") - print(f"Work dir : {workdir}") - print(f"NRes archives : {nres_count}") - print(f"RsLi archives : {rsli_count}") - print(f"Roundtrip match: {matches}/{len(report['results'])}") - print(f"Doc issues : {issues_total}") - - if mismatches: - print("\nMismatches:") - for row in report["results"]: - if row["match"]: - continue - print( - f"- {row['relative_path']} [{row['type']}] " - f"diff@{row['first_diff_offset']}: {row['first_diff']}" - ) - - if issues_total: - print("\nIssues:") - for row in report["results"]: - if not row["issues"]: - continue - print(f"- {row['relative_path']} [{row['type']}]") - for issue in row["issues"]: - print(f" * {issue}") - - finally: - if temp_created or args.cleanup: - shutil.rmtree(workdir, ignore_errors=True) - - if failures > 0: - return 1 - if report["summary"].get("mismatches", 0) > 0 and args.fail_on_diff: - return 1 - return 0 - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description="NRes/RsLi tools: scan, unpack, repack, and roundtrip validation." - ) - sub = parser.add_subparsers(dest="command", required=True) - - scan = sub.add_parser("scan", help="Scan files by header signatures.") - scan.add_argument("--input", required=True, help="Root directory to scan.") - scan.add_argument("--json", action="store_true", help="Print JSON output.") - scan.set_defaults(func=cmd_scan) - - nres_unpack = sub.add_parser("nres-unpack", help="Unpack a single NRes archive.") - nres_unpack.add_argument("--archive", required=True, help="Path to NRes file.") - nres_unpack.add_argument("--output", required=True, help="Output directory.") - nres_unpack.set_defaults(func=cmd_nres_unpack) - - nres_pack = sub.add_parser("nres-pack", help="Pack NRes archive from manifest.") - nres_pack.add_argument("--manifest", required=True, help="Path to manifest.json.") - nres_pack.add_argument("--output", required=True, help="Output file path.") - nres_pack.set_defaults(func=cmd_nres_pack) - - rsli_unpack = sub.add_parser("rsli-unpack", help="Unpack a single RsLi archive.") - rsli_unpack.add_argument("--archive", required=True, help="Path to RsLi file.") - rsli_unpack.add_argument("--output", required=True, help="Output directory.") - rsli_unpack.set_defaults(func=cmd_rsli_unpack) - - rsli_pack = sub.add_parser("rsli-pack", help="Pack RsLi archive from manifest.") - rsli_pack.add_argument("--manifest", required=True, help="Path to manifest.json.") - rsli_pack.add_argument("--output", required=True, help="Output file path.") - rsli_pack.set_defaults(func=cmd_rsli_pack) - - validate = sub.add_parser( - "validate", - help="Scan all archives and run unpack->repack->byte-compare validation.", - ) - validate.add_argument("--input", required=True, help="Root with game data files.") - validate.add_argument( - "--workdir", - help="Working directory for temporary unpack/repack files. " - "If omitted, a temporary directory is used and removed automatically.", - ) - validate.add_argument("--report", help="Optional JSON report output path.") - validate.add_argument( - "--fail-on-diff", - action="store_true", - help="Return non-zero exit code if any byte mismatch exists.", - ) - validate.add_argument( - "--fail-on-issues", - action="store_true", - help="Return non-zero exit code if any spec issue was detected.", - ) - validate.add_argument( - "--cleanup", - action="store_true", - help="Remove --workdir after completion.", - ) - validate.set_defaults(func=cmd_validate) - - return parser - - -def main() -> int: - parser = build_parser() - args = parser.parse_args() - return int(args.func(args)) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/tools/init_testdata.py b/tools/init_testdata.py deleted file mode 100644 index 4079cdb..0000000 --- a/tools/init_testdata.py +++ /dev/null @@ -1,204 +0,0 @@ -#!/usr/bin/env python3 -""" -Initialize test data folders by archive signatures. - -The script scans all files in --input and copies matching archives into: - --output/nres/<relative path> - --output/rsli/<relative path> -""" - -from __future__ import annotations - -import argparse -import shutil -import sys -from pathlib import Path - -MAGIC_NRES = b"NRes" -MAGIC_RSLI = b"NL\x00\x01" - - -def is_relative_to(path: Path, base: Path) -> bool: - try: - path.relative_to(base) - except ValueError: - return False - return True - - -def detect_archive_type(path: Path) -> str | None: - try: - with path.open("rb") as handle: - magic = handle.read(4) - except OSError as exc: - print(f"[warn] cannot read {path}: {exc}", file=sys.stderr) - return None - - if magic == MAGIC_NRES: - return "nres" - if magic == MAGIC_RSLI: - return "rsli" - return None - - -def scan_archives(input_root: Path, excluded_root: Path | None) -> list[tuple[Path, str]]: - found: list[tuple[Path, str]] = [] - for path in sorted(input_root.rglob("*")): - if not path.is_file(): - continue - if excluded_root and is_relative_to(path.resolve(), excluded_root): - continue - - archive_type = detect_archive_type(path) - if archive_type: - found.append((path, archive_type)) - return found - - -def confirm_overwrite(path: Path) -> str: - prompt = ( - f"File exists: {path}\n" - "Overwrite? [y]es / [n]o / [a]ll / [q]uit (default: n): " - ) - while True: - try: - answer = input(prompt).strip().lower() - except EOFError: - return "quit" - - if answer in {"", "n", "no"}: - return "no" - if answer in {"y", "yes"}: - return "yes" - if answer in {"a", "all"}: - return "all" - if answer in {"q", "quit"}: - return "quit" - print("Please answer with y, n, a, or q.") - - -def copy_archives( - archives: list[tuple[Path, str]], - input_root: Path, - output_root: Path, - force: bool, -) -> int: - copied = 0 - skipped = 0 - overwritten = 0 - overwrite_all = force - - type_counts = {"nres": 0, "rsli": 0} - for _, archive_type in archives: - type_counts[archive_type] += 1 - - print( - f"Found archives: total={len(archives)}, " - f"nres={type_counts['nres']}, rsli={type_counts['rsli']}" - ) - - for source, archive_type in archives: - rel_path = source.relative_to(input_root) - destination = output_root / archive_type / rel_path - destination.parent.mkdir(parents=True, exist_ok=True) - - if destination.exists(): - if destination.is_dir(): - print( - f"[error] destination is a directory, expected file: {destination}", - file=sys.stderr, - ) - return 2 - - if not overwrite_all: - if not sys.stdin.isatty(): - print( - "[error] destination file exists but stdin is not interactive. " - "Use --force to overwrite without prompts.", - file=sys.stderr, - ) - return 2 - - decision = confirm_overwrite(destination) - if decision == "quit": - print("Aborted by user.") - return 130 - if decision == "no": - skipped += 1 - continue - if decision == "all": - overwrite_all = True - - overwritten += 1 - - try: - shutil.copy2(source, destination) - except OSError as exc: - print(f"[error] failed to copy {source} -> {destination}: {exc}", file=sys.stderr) - return 2 - copied += 1 - - print( - f"Done: copied={copied}, overwritten={overwritten}, skipped={skipped}, " - f"output={output_root}" - ) - return 0 - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description="Initialize test data by scanning NRes/RsLi signatures." - ) - parser.add_argument( - "--input", - required=True, - help="Input directory to scan recursively.", - ) - parser.add_argument( - "--output", - required=True, - help="Output root directory (archives go to nres/ and rsli/ subdirs).", - ) - parser.add_argument( - "--force", - action="store_true", - help="Overwrite destination files without confirmation prompts.", - ) - return parser - - -def main() -> int: - args = build_parser().parse_args() - - input_root = Path(args.input) - if not input_root.exists(): - print(f"[error] input directory does not exist: {input_root}", file=sys.stderr) - return 2 - if not input_root.is_dir(): - print(f"[error] input path is not a directory: {input_root}", file=sys.stderr) - return 2 - - output_root = Path(args.output) - if output_root.exists() and not output_root.is_dir(): - print(f"[error] output path exists and is not a directory: {output_root}", file=sys.stderr) - return 2 - - input_resolved = input_root.resolve() - output_resolved = output_root.resolve() - if input_resolved == output_resolved: - print("[error] input and output directories must be different.", file=sys.stderr) - return 2 - - excluded_root: Path | None = None - if is_relative_to(output_resolved, input_resolved): - excluded_root = output_resolved - print(f"Notice: output is inside input, skipping scan under: {excluded_root}") - - archives = scan_archives(input_root, excluded_root) - - output_root.mkdir(parents=True, exist_ok=True) - return copy_archives(archives, input_root, output_root, force=args.force) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/tools/msh_doc_validator.py b/tools/msh_doc_validator.py deleted file mode 100644 index ff096a4..0000000 --- a/tools/msh_doc_validator.py +++ /dev/null @@ -1,1000 +0,0 @@ -#!/usr/bin/env python3 -""" -Validate assumptions from docs/specs/msh.md on real game archives. - -The tool checks three groups: -1) MSH model payloads (nested NRes in *.msh entries), -2) Texm texture payloads, -3) FXID effect payloads. -""" - -from __future__ import annotations - -import argparse -import json -import math -import struct -from collections import Counter -from pathlib import Path -from typing import Any - -import archive_roundtrip_validator as arv - -MAGIC_NRES = b"NRes" -MAGIC_PAGE = b"Page" - -TYPE_FXID = 0x44495846 -TYPE_TEXM = 0x6D786554 - -FX_CMD_SIZE = {1: 224, 2: 148, 3: 200, 4: 204, 5: 112, 6: 4, 7: 208, 8: 248, 9: 208, 10: 208} -TEXM_KNOWN_FORMATS = {0, 565, 556, 4444, 888, 8888} - - -def _add_issue( - issues: list[dict[str, Any]], - severity: str, - category: str, - archive: Path, - entry_name: str | None, - message: str, -) -> None: - issues.append( - { - "severity": severity, - "category": category, - "archive": str(archive), - "entry": entry_name, - "message": message, - } - ) - - -def _entry_payload(blob: bytes, entry: dict[str, Any]) -> bytes: - start = int(entry["data_offset"]) - end = start + int(entry["size"]) - return blob[start:end] - - -def _entry_by_type(entries: list[dict[str, Any]]) -> dict[int, list[dict[str, Any]]]: - by_type: dict[int, list[dict[str, Any]]] = {} - for item in entries: - by_type.setdefault(int(item["type_id"]), []).append(item) - return by_type - - -def _expect_single_resource( - by_type: dict[int, list[dict[str, Any]]], - type_id: int, - label: str, - issues: list[dict[str, Any]], - archive: Path, - model_name: str, - required: bool, -) -> dict[str, Any] | None: - rows = by_type.get(type_id, []) - if not rows: - if required: - _add_issue( - issues, - "error", - "model-resource", - archive, - model_name, - f"missing required resource type={type_id} ({label})", - ) - return None - if len(rows) > 1: - _add_issue( - issues, - "warning", - "model-resource", - archive, - model_name, - f"multiple resources type={type_id} ({label}); using first entry", - ) - return rows[0] - - -def _check_fixed_stride( - *, - entry: dict[str, Any], - stride: int, - label: str, - issues: list[dict[str, Any]], - archive: Path, - model_name: str, - enforce_attr3: bool = True, - enforce_attr2_zero: bool = True, -) -> int: - size = int(entry["size"]) - attr1 = int(entry["attr1"]) - attr2 = int(entry["attr2"]) - attr3 = int(entry["attr3"]) - - count = -1 - if size % stride != 0: - _add_issue( - issues, - "error", - "model-stride", - archive, - model_name, - f"{label}: size={size} is not divisible by stride={stride}", - ) - else: - count = size // stride - if attr1 != count: - _add_issue( - issues, - "error", - "model-attr", - archive, - model_name, - f"{label}: attr1={attr1} != size/stride={count}", - ) - if enforce_attr3 and attr3 != stride: - _add_issue( - issues, - "error", - "model-attr", - archive, - model_name, - f"{label}: attr3={attr3} != {stride}", - ) - if enforce_attr2_zero and attr2 != 0: - _add_issue( - issues, - "warning", - "model-attr", - archive, - model_name, - f"{label}: attr2={attr2} (expected 0 in known assets)", - ) - return count - - -def _validate_res10( - data: bytes, - node_count: int, - issues: list[dict[str, Any]], - archive: Path, - model_name: str, -) -> None: - off = 0 - for idx in range(node_count): - if off + 4 > len(data): - _add_issue( - issues, - "error", - "res10", - archive, - model_name, - f"record {idx}: missing u32 length (offset={off}, size={len(data)})", - ) - return - ln = struct.unpack_from("<I", data, off)[0] - off += 4 - need = ln + 1 if ln else 0 - if off + need > len(data): - _add_issue( - issues, - "error", - "res10", - archive, - model_name, - f"record {idx}: out of bounds (len={ln}, need={need}, offset={off}, size={len(data)})", - ) - return - if ln and data[off + ln] != 0: - _add_issue( - issues, - "warning", - "res10", - archive, - model_name, - f"record {idx}: missing trailing NUL at payload end", - ) - off += need - - if off != len(data): - _add_issue( - issues, - "error", - "res10", - archive, - model_name, - f"tail bytes after node records: consumed={off}, size={len(data)}", - ) - - -def _validate_model_payload( - model_blob: bytes, - archive: Path, - model_name: str, - issues: list[dict[str, Any]], - counters: Counter[str], -) -> None: - counters["models_total"] += 1 - - if model_blob[:4] != MAGIC_NRES: - _add_issue( - issues, - "error", - "model-container", - archive, - model_name, - "payload is not NRes (missing magic)", - ) - return - - try: - parsed = arv.parse_nres(model_blob, source=f"{archive}:{model_name}") - except Exception as exc: # pylint: disable=broad-except - _add_issue( - issues, - "error", - "model-container", - archive, - model_name, - f"cannot parse nested NRes: {exc}", - ) - return - - for item in parsed.get("issues", []): - _add_issue(issues, "warning", "model-container", archive, model_name, str(item)) - - entries = parsed["entries"] - by_type = _entry_by_type(entries) - - res1 = _expect_single_resource(by_type, 1, "Res1", issues, archive, model_name, True) - res2 = _expect_single_resource(by_type, 2, "Res2", issues, archive, model_name, True) - res3 = _expect_single_resource(by_type, 3, "Res3", issues, archive, model_name, True) - res4 = _expect_single_resource(by_type, 4, "Res4", issues, archive, model_name, False) - res5 = _expect_single_resource(by_type, 5, "Res5", issues, archive, model_name, False) - res6 = _expect_single_resource(by_type, 6, "Res6", issues, archive, model_name, True) - res7 = _expect_single_resource(by_type, 7, "Res7", issues, archive, model_name, False) - res8 = _expect_single_resource(by_type, 8, "Res8", issues, archive, model_name, False) - res10 = _expect_single_resource(by_type, 10, "Res10", issues, archive, model_name, False) - res13 = _expect_single_resource(by_type, 13, "Res13", issues, archive, model_name, True) - res15 = _expect_single_resource(by_type, 15, "Res15", issues, archive, model_name, False) - res16 = _expect_single_resource(by_type, 16, "Res16", issues, archive, model_name, False) - res18 = _expect_single_resource(by_type, 18, "Res18", issues, archive, model_name, False) - res19 = _expect_single_resource(by_type, 19, "Res19", issues, archive, model_name, False) - - if not (res1 and res2 and res3 and res6 and res13): - return - - # Res1 - res1_stride = int(res1["attr3"]) - if res1_stride not in (38, 24): - _add_issue( - issues, - "warning", - "res1", - archive, - model_name, - f"unexpected Res1 stride attr3={res1_stride} (known: 38 or 24)", - ) - if res1_stride <= 0: - _add_issue(issues, "error", "res1", archive, model_name, f"invalid Res1 stride={res1_stride}") - return - if int(res1["size"]) % res1_stride != 0: - _add_issue( - issues, - "error", - "res1", - archive, - model_name, - f"Res1 size={res1['size']} not divisible by stride={res1_stride}", - ) - return - node_count = int(res1["size"]) // res1_stride - if int(res1["attr1"]) != node_count: - _add_issue( - issues, - "error", - "res1", - archive, - model_name, - f"Res1 attr1={res1['attr1']} != node_count={node_count}", - ) - - # Res2 - res2_size = int(res2["size"]) - res2_attr1 = int(res2["attr1"]) - res2_attr2 = int(res2["attr2"]) - res2_attr3 = int(res2["attr3"]) - if res2_size < 0x8C: - _add_issue(issues, "error", "res2", archive, model_name, f"Res2 too small: size={res2_size}") - return - slot_bytes = res2_size - 0x8C - slot_count = -1 - if slot_bytes % 68 != 0: - _add_issue( - issues, - "error", - "res2", - archive, - model_name, - f"Res2 slot area not divisible by 68: slot_bytes={slot_bytes}", - ) - else: - slot_count = slot_bytes // 68 - if res2_attr1 != slot_count: - _add_issue( - issues, - "error", - "res2", - archive, - model_name, - f"Res2 attr1={res2_attr1} != slot_count={slot_count}", - ) - if res2_attr2 != 0: - _add_issue( - issues, - "warning", - "res2", - archive, - model_name, - f"Res2 attr2={res2_attr2} (expected 0 in known assets)", - ) - if res2_attr3 != 68: - _add_issue( - issues, - "error", - "res2", - archive, - model_name, - f"Res2 attr3={res2_attr3} != 68", - ) - - # Fixed-stride resources - vertex_count = _check_fixed_stride( - entry=res3, - stride=12, - label="Res3", - issues=issues, - archive=archive, - model_name=model_name, - ) - _ = _check_fixed_stride( - entry=res4, - stride=4, - label="Res4", - issues=issues, - archive=archive, - model_name=model_name, - ) if res4 else None - _ = _check_fixed_stride( - entry=res5, - stride=4, - label="Res5", - issues=issues, - archive=archive, - model_name=model_name, - ) if res5 else None - index_count = _check_fixed_stride( - entry=res6, - stride=2, - label="Res6", - issues=issues, - archive=archive, - model_name=model_name, - ) - tri_desc_count = _check_fixed_stride( - entry=res7, - stride=16, - label="Res7", - issues=issues, - archive=archive, - model_name=model_name, - ) if res7 else -1 - anim_key_count = _check_fixed_stride( - entry=res8, - stride=24, - label="Res8", - issues=issues, - archive=archive, - model_name=model_name, - enforce_attr3=False, # format stores attr3=4 in data set - ) if res8 else -1 - if res8 and int(res8["attr3"]) != 4: - _add_issue( - issues, - "error", - "res8", - archive, - model_name, - f"Res8 attr3={res8['attr3']} != 4", - ) - if res13: - batch_count = _check_fixed_stride( - entry=res13, - stride=20, - label="Res13", - issues=issues, - archive=archive, - model_name=model_name, - ) - else: - batch_count = -1 - if res15: - _check_fixed_stride( - entry=res15, - stride=8, - label="Res15", - issues=issues, - archive=archive, - model_name=model_name, - ) - if res16: - _check_fixed_stride( - entry=res16, - stride=8, - label="Res16", - issues=issues, - archive=archive, - model_name=model_name, - ) - if res18: - _check_fixed_stride( - entry=res18, - stride=4, - label="Res18", - issues=issues, - archive=archive, - model_name=model_name, - ) - - if res19: - anim_map_count = _check_fixed_stride( - entry=res19, - stride=2, - label="Res19", - issues=issues, - archive=archive, - model_name=model_name, - enforce_attr3=False, - enforce_attr2_zero=False, - ) - if int(res19["attr3"]) != 2: - _add_issue( - issues, - "error", - "res19", - archive, - model_name, - f"Res19 attr3={res19['attr3']} != 2", - ) - else: - anim_map_count = -1 - - # Res10 - if res10: - if int(res10["attr1"]) != int(res1["attr1"]): - _add_issue( - issues, - "error", - "res10", - archive, - model_name, - f"Res10 attr1={res10['attr1']} != Res1.attr1={res1['attr1']}", - ) - if int(res10["attr3"]) != 0: - _add_issue( - issues, - "warning", - "res10", - archive, - model_name, - f"Res10 attr3={res10['attr3']} (known assets use 0)", - ) - _validate_res10(_entry_payload(model_blob, res10), node_count, issues, archive, model_name) - - # Cross-table checks. - if vertex_count > 0 and (res4 and int(res4["size"]) // 4 != vertex_count): - _add_issue(issues, "error", "model-cross", archive, model_name, "Res4 count != Res3 count") - if vertex_count > 0 and (res5 and int(res5["size"]) // 4 != vertex_count): - _add_issue(issues, "error", "model-cross", archive, model_name, "Res5 count != Res3 count") - - indices: list[int] = [] - if index_count > 0: - res6_data = _entry_payload(model_blob, res6) - indices = list(struct.unpack_from(f"<{index_count}H", res6_data, 0)) - - if batch_count > 0: - res13_data = _entry_payload(model_blob, res13) - for batch_idx in range(batch_count): - b_off = batch_idx * 20 - ( - _batch_flags, - _mat_idx, - _unk4, - _unk6, - idx_count, - idx_start, - _unk14, - base_vertex, - ) = struct.unpack_from("<HHHHHIHI", res13_data, b_off) - end = idx_start + idx_count - if index_count > 0 and end > index_count: - _add_issue( - issues, - "error", - "res13", - archive, - model_name, - f"batch {batch_idx}: index range [{idx_start}, {end}) outside Res6 count={index_count}", - ) - continue - if idx_count % 3 != 0: - _add_issue( - issues, - "warning", - "res13", - archive, - model_name, - f"batch {batch_idx}: indexCount={idx_count} is not divisible by 3", - ) - if vertex_count > 0 and index_count > 0 and idx_count > 0: - raw_slice = indices[idx_start:end] - max_raw = max(raw_slice) - if base_vertex + max_raw >= vertex_count: - _add_issue( - issues, - "error", - "res13", - archive, - model_name, - f"batch {batch_idx}: baseVertex+maxIndex={base_vertex + max_raw} >= vertex_count={vertex_count}", - ) - - if slot_count > 0: - res2_data = _entry_payload(model_blob, res2) - for slot_idx in range(slot_count): - s_off = 0x8C + slot_idx * 68 - tri_start, tri_count, batch_start, slot_batch_count = struct.unpack_from("<4H", res2_data, s_off) - if tri_desc_count > 0 and tri_start + tri_count > tri_desc_count: - _add_issue( - issues, - "error", - "res2-slot", - archive, - model_name, - f"slot {slot_idx}: tri range [{tri_start}, {tri_start + tri_count}) outside Res7 count={tri_desc_count}", - ) - if batch_count > 0 and batch_start + slot_batch_count > batch_count: - _add_issue( - issues, - "error", - "res2-slot", - archive, - model_name, - f"slot {slot_idx}: batch range [{batch_start}, {batch_start + slot_batch_count}) outside Res13 count={batch_count}", - ) - # Slot bounds are 10 float values. - for f_idx in range(10): - value = struct.unpack_from("<f", res2_data, s_off + 8 + f_idx * 4)[0] - if not math.isfinite(value): - _add_issue( - issues, - "error", - "res2-slot", - archive, - model_name, - f"slot {slot_idx}: non-finite bound float at field {f_idx}", - ) - break - - if tri_desc_count > 0: - res7_data = _entry_payload(model_blob, res7) - for tri_idx in range(tri_desc_count): - t_off = tri_idx * 16 - _flags, l0, l1, l2 = struct.unpack_from("<4H", res7_data, t_off) - for link in (l0, l1, l2): - if link != 0xFFFF and link >= tri_desc_count: - _add_issue( - issues, - "error", - "res7", - archive, - model_name, - f"tri {tri_idx}: link {link} outside tri_desc_count={tri_desc_count}", - ) - _ = struct.unpack_from("<H", res7_data, t_off + 14)[0] - - # Node-level constraints for slot matrix / animation mapping. - if res1_stride == 38: - res1_data = _entry_payload(model_blob, res1) - map_words: list[int] = [] - if anim_map_count > 0 and res19: - res19_data = _entry_payload(model_blob, res19) - map_words = list(struct.unpack_from(f"<{anim_map_count}H", res19_data, 0)) - frame_count = int(res19["attr2"]) if res19 else 0 - - for node_idx in range(node_count): - n_off = node_idx * 38 - hdr2 = struct.unpack_from("<H", res1_data, n_off + 4)[0] - hdr3 = struct.unpack_from("<H", res1_data, n_off + 6)[0] - # Slot matrix: 15 uint16 at +8. - for w_idx in range(15): - slot_idx = struct.unpack_from("<H", res1_data, n_off + 8 + w_idx * 2)[0] - if slot_idx != 0xFFFF and slot_count > 0 and slot_idx >= slot_count: - _add_issue( - issues, - "error", - "res1-slot", - archive, - model_name, - f"node {node_idx}: slotIndex[{w_idx}]={slot_idx} outside slot_count={slot_count}", - ) - - if anim_key_count > 0 and hdr3 != 0xFFFF and hdr3 >= anim_key_count: - _add_issue( - issues, - "error", - "res1-anim", - archive, - model_name, - f"node {node_idx}: fallbackKeyIndex={hdr3} outside Res8 count={anim_key_count}", - ) - if map_words and hdr2 != 0xFFFF and frame_count > 0: - end = hdr2 + frame_count - if end > len(map_words): - _add_issue( - issues, - "error", - "res19-map", - archive, - model_name, - f"node {node_idx}: map range [{hdr2}, {end}) outside Res19 count={len(map_words)}", - ) - - counters["models_ok"] += 1 - - -def _validate_texm_payload( - payload: bytes, - archive: Path, - entry_name: str, - issues: list[dict[str, Any]], - counters: Counter[str], -) -> None: - counters["texm_total"] += 1 - - if len(payload) < 32: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"payload too small: {len(payload)}", - ) - return - - magic, width, height, mip_count, flags4, flags5, unk6, fmt = struct.unpack_from("<8I", payload, 0) - if magic != TYPE_TEXM: - _add_issue(issues, "error", "texm", archive, entry_name, f"magic=0x{magic:08X} != Texm") - return - if width == 0 or height == 0: - _add_issue(issues, "error", "texm", archive, entry_name, f"invalid size {width}x{height}") - return - if mip_count == 0: - _add_issue(issues, "error", "texm", archive, entry_name, "mipCount=0") - return - if fmt not in TEXM_KNOWN_FORMATS: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"unknown format code {fmt}", - ) - return - if flags4 not in (0, 32): - _add_issue( - issues, - "warning", - "texm", - archive, - entry_name, - f"flags4={flags4} (known values: 0 or 32)", - ) - if flags5 not in (0, 0x04000000, 0x00800000): - _add_issue( - issues, - "warning", - "texm", - archive, - entry_name, - f"flags5=0x{flags5:08X} (known values: 0, 0x00800000, 0x04000000)", - ) - - bpp = 1 if fmt == 0 else (2 if fmt in (565, 556, 4444) else 4) - pix_sum = 0 - w = width - h = height - for _ in range(mip_count): - pix_sum += w * h - w = max(1, w >> 1) - h = max(1, h >> 1) - size_core = 32 + (1024 if fmt == 0 else 0) + bpp * pix_sum - if size_core > len(payload): - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"sizeCore={size_core} exceeds payload size={len(payload)}", - ) - return - - tail = len(payload) - size_core - if tail > 0: - off = size_core - if tail < 8: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"tail too short for Page chunk: tail={tail}", - ) - return - if payload[off : off + 4] != MAGIC_PAGE: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"tail is present but no Page magic at offset {off}", - ) - return - rect_count = struct.unpack_from("<I", payload, off + 4)[0] - need = 8 + rect_count * 8 - if need > tail: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"Page chunk truncated: need={need}, tail={tail}", - ) - return - if need != tail: - _add_issue( - issues, - "error", - "texm", - archive, - entry_name, - f"extra bytes after Page chunk: tail={tail}, pageSize={need}", - ) - return - - _ = unk6 # carried as raw field in spec, semantics intentionally unknown. - counters["texm_ok"] += 1 - - -def _validate_fxid_payload( - payload: bytes, - archive: Path, - entry_name: str, - issues: list[dict[str, Any]], - counters: Counter[str], -) -> None: - counters["fxid_total"] += 1 - - if len(payload) < 60: - _add_issue( - issues, - "error", - "fxid", - archive, - entry_name, - f"payload too small: {len(payload)}", - ) - return - - cmd_count = struct.unpack_from("<I", payload, 0)[0] - ptr = 0x3C - for idx in range(cmd_count): - if ptr + 4 > len(payload): - _add_issue( - issues, - "error", - "fxid", - archive, - entry_name, - f"command {idx}: missing header at offset={ptr}", - ) - return - word = struct.unpack_from("<I", payload, ptr)[0] - opcode = word & 0xFF - if opcode not in FX_CMD_SIZE: - _add_issue( - issues, - "error", - "fxid", - archive, - entry_name, - f"command {idx}: unknown opcode={opcode} at offset={ptr}", - ) - return - size = FX_CMD_SIZE[opcode] - if ptr + size > len(payload): - _add_issue( - issues, - "error", - "fxid", - archive, - entry_name, - f"command {idx}: truncated, need end={ptr + size}, payload={len(payload)}", - ) - return - ptr += size - - if ptr != len(payload): - _add_issue( - issues, - "error", - "fxid", - archive, - entry_name, - f"tail bytes after command stream: parsed_end={ptr}, payload={len(payload)}", - ) - return - - counters["fxid_ok"] += 1 - - -def _scan_nres_files(root: Path) -> list[Path]: - rows = arv.scan_archives(root) - out: list[Path] = [] - for item in rows: - if item["type"] != "nres": - continue - out.append(root / item["relative_path"]) - return out - - -def run_validation(input_root: Path) -> dict[str, Any]: - archives = _scan_nres_files(input_root) - issues: list[dict[str, Any]] = [] - counters: Counter[str] = Counter() - - for archive_path in archives: - counters["archives_total"] += 1 - data = archive_path.read_bytes() - try: - parsed = arv.parse_nres(data, source=str(archive_path)) - except Exception as exc: # pylint: disable=broad-except - _add_issue(issues, "error", "archive", archive_path, None, f"cannot parse NRes: {exc}") - continue - - for item in parsed.get("issues", []): - _add_issue(issues, "warning", "archive", archive_path, None, str(item)) - - for entry in parsed["entries"]: - name = str(entry["name"]) - payload = _entry_payload(data, entry) - type_id = int(entry["type_id"]) - - if name.lower().endswith(".msh"): - _validate_model_payload(payload, archive_path, name, issues, counters) - - if type_id == TYPE_TEXM: - _validate_texm_payload(payload, archive_path, name, issues, counters) - - if type_id == TYPE_FXID: - _validate_fxid_payload(payload, archive_path, name, issues, counters) - - errors = sum(1 for row in issues if row["severity"] == "error") - warnings = sum(1 for row in issues if row["severity"] == "warning") - - return { - "input_root": str(input_root), - "summary": { - "archives_total": counters["archives_total"], - "models_total": counters["models_total"], - "models_ok": counters["models_ok"], - "texm_total": counters["texm_total"], - "texm_ok": counters["texm_ok"], - "fxid_total": counters["fxid_total"], - "fxid_ok": counters["fxid_ok"], - "errors": errors, - "warnings": warnings, - "issues_total": len(issues), - }, - "issues": issues, - } - - -def cmd_scan(args: argparse.Namespace) -> int: - root = Path(args.input).resolve() - report = run_validation(root) - summary = report["summary"] - print(f"Input root : {root}") - print(f"NRes archives : {summary['archives_total']}") - print(f"MSH models : {summary['models_total']}") - print(f"Texm textures : {summary['texm_total']}") - print(f"FXID effects : {summary['fxid_total']}") - return 0 - - -def cmd_validate(args: argparse.Namespace) -> int: - root = Path(args.input).resolve() - report = run_validation(root) - summary = report["summary"] - - if args.report: - arv.dump_json(Path(args.report).resolve(), report) - - print(f"Input root : {root}") - print(f"NRes archives : {summary['archives_total']}") - print(f"MSH models : {summary['models_ok']}/{summary['models_total']} valid") - print(f"Texm textures : {summary['texm_ok']}/{summary['texm_total']} valid") - print(f"FXID effects : {summary['fxid_ok']}/{summary['fxid_total']} valid") - print(f"Issues : {summary['issues_total']} (errors={summary['errors']}, warnings={summary['warnings']})") - - if report["issues"]: - limit = max(1, int(args.print_limit)) - print("\nSample issues:") - for item in report["issues"][:limit]: - where = item["archive"] - if item["entry"]: - where = f"{where}::{item['entry']}" - print(f"- [{item['severity']}] [{item['category']}] {where}: {item['message']}") - if len(report["issues"]) > limit: - print(f"... and {len(report['issues']) - limit} more issue(s)") - - if summary["errors"] > 0: - return 1 - if args.fail_on_warnings and summary["warnings"] > 0: - return 1 - return 0 - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description="Validate docs/specs/msh.md assumptions on real archives." - ) - sub = parser.add_subparsers(dest="command", required=True) - - scan = sub.add_parser("scan", help="Quick scan and counts (models/textures/effects).") - scan.add_argument("--input", required=True, help="Root directory with game/test archives.") - scan.set_defaults(func=cmd_scan) - - validate = sub.add_parser("validate", help="Run full spec validation.") - validate.add_argument("--input", required=True, help="Root directory with game/test archives.") - validate.add_argument("--report", help="Optional JSON report output path.") - validate.add_argument( - "--print-limit", - type=int, - default=50, - help="How many issues to print to stdout (default: 50).", - ) - validate.add_argument( - "--fail-on-warnings", - action="store_true", - help="Return non-zero if warnings are present.", - ) - validate.set_defaults(func=cmd_validate) - - return parser - - -def main() -> int: - parser = build_parser() - args = parser.parse_args() - return int(args.func(args)) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/tools/msh_export_obj.py b/tools/msh_export_obj.py deleted file mode 100644 index 75a9602..0000000 --- a/tools/msh_export_obj.py +++ /dev/null @@ -1,357 +0,0 @@ -#!/usr/bin/env python3 -""" -Export NGI MSH geometry to Wavefront OBJ. - -The exporter is intended for inspection/debugging and uses the same -batch/slot selection logic as msh_preview_renderer.py. -""" - -from __future__ import annotations - -import argparse -import math -import struct -from pathlib import Path -from typing import Any - -import archive_roundtrip_validator as arv - -MAGIC_NRES = b"NRes" - - -def _entry_payload(blob: bytes, entry: dict[str, Any]) -> bytes: - start = int(entry["data_offset"]) - end = start + int(entry["size"]) - return blob[start:end] - - -def _parse_nres(blob: bytes, source: str) -> dict[str, Any]: - if blob[:4] != MAGIC_NRES: - raise RuntimeError(f"{source}: not an NRes payload") - return arv.parse_nres(blob, source=source) - - -def _by_type(entries: list[dict[str, Any]]) -> dict[int, list[dict[str, Any]]]: - out: dict[int, list[dict[str, Any]]] = {} - for row in entries: - out.setdefault(int(row["type_id"]), []).append(row) - return out - - -def _get_single(by_type: dict[int, list[dict[str, Any]]], type_id: int, label: str) -> dict[str, Any]: - rows = by_type.get(type_id, []) - if not rows: - raise RuntimeError(f"missing resource type {type_id} ({label})") - return rows[0] - - -def _pick_model_payload(archive_path: Path, model_name: str | None) -> tuple[bytes, str]: - root_blob = archive_path.read_bytes() - parsed = _parse_nres(root_blob, str(archive_path)) - - msh_entries = [row for row in parsed["entries"] if str(row["name"]).lower().endswith(".msh")] - if msh_entries: - chosen: dict[str, Any] | None = None - if model_name: - model_l = model_name.lower() - for row in msh_entries: - name_l = str(row["name"]).lower() - if name_l == model_l: - chosen = row - break - if chosen is None: - for row in msh_entries: - if str(row["name"]).lower().startswith(model_l): - chosen = row - break - else: - chosen = msh_entries[0] - - if chosen is None: - names = ", ".join(str(row["name"]) for row in msh_entries[:12]) - raise RuntimeError( - f"model '{model_name}' not found in {archive_path}. Available: {names}" - ) - return _entry_payload(root_blob, chosen), str(chosen["name"]) - - by_type = _by_type(parsed["entries"]) - if all(k in by_type for k in (1, 2, 3, 6, 13)): - return root_blob, archive_path.name - - raise RuntimeError( - f"{archive_path} does not contain .msh entries and does not look like a direct model payload" - ) - - -def _extract_geometry( - model_blob: bytes, - *, - lod: int, - group: int, - max_faces: int, - all_batches: bool, -) -> tuple[list[tuple[float, float, float]], list[tuple[int, int, int]], dict[str, int]]: - parsed = _parse_nres(model_blob, "<model>") - by_type = _by_type(parsed["entries"]) - - res1 = _get_single(by_type, 1, "Res1") - res2 = _get_single(by_type, 2, "Res2") - res3 = _get_single(by_type, 3, "Res3") - res6 = _get_single(by_type, 6, "Res6") - res13 = _get_single(by_type, 13, "Res13") - - pos_blob = _entry_payload(model_blob, res3) - if len(pos_blob) % 12 != 0: - raise RuntimeError(f"Res3 size is not divisible by 12: {len(pos_blob)}") - vertex_count = len(pos_blob) // 12 - positions = [struct.unpack_from("<3f", pos_blob, i * 12) for i in range(vertex_count)] - - idx_blob = _entry_payload(model_blob, res6) - if len(idx_blob) % 2 != 0: - raise RuntimeError(f"Res6 size is not divisible by 2: {len(idx_blob)}") - index_count = len(idx_blob) // 2 - indices = list(struct.unpack_from(f"<{index_count}H", idx_blob, 0)) - - batch_blob = _entry_payload(model_blob, res13) - if len(batch_blob) % 20 != 0: - raise RuntimeError(f"Res13 size is not divisible by 20: {len(batch_blob)}") - batch_count = len(batch_blob) // 20 - batches: list[tuple[int, int, int, int]] = [] - for i in range(batch_count): - off = i * 20 - idx_count = struct.unpack_from("<H", batch_blob, off + 8)[0] - idx_start = struct.unpack_from("<I", batch_blob, off + 10)[0] - base_vertex = struct.unpack_from("<I", batch_blob, off + 16)[0] - batches.append((idx_count, idx_start, base_vertex, i)) - - res2_blob = _entry_payload(model_blob, res2) - if len(res2_blob) < 0x8C: - raise RuntimeError("Res2 is too small (< 0x8C)") - slot_blob = res2_blob[0x8C:] - if len(slot_blob) % 68 != 0: - raise RuntimeError(f"Res2 slot area is not divisible by 68: {len(slot_blob)}") - slot_count = len(slot_blob) // 68 - slots: list[tuple[int, int, int, int]] = [] - for i in range(slot_count): - off = i * 68 - tri_start, tri_count, batch_start, slot_batch_count = struct.unpack_from("<4H", slot_blob, off) - slots.append((tri_start, tri_count, batch_start, slot_batch_count)) - - res1_blob = _entry_payload(model_blob, res1) - node_stride = int(res1["attr3"]) - node_count = int(res1["attr1"]) - node_slot_indices: list[int] = [] - if not all_batches and node_stride >= 38 and len(res1_blob) >= node_count * node_stride: - if lod < 0 or lod > 2: - raise RuntimeError(f"lod must be 0..2 (got {lod})") - if group < 0 or group > 4: - raise RuntimeError(f"group must be 0..4 (got {group})") - matrix_index = lod * 5 + group - for n in range(node_count): - off = n * node_stride + 8 + matrix_index * 2 - slot_idx = struct.unpack_from("<H", res1_blob, off)[0] - if slot_idx == 0xFFFF: - continue - if slot_idx >= slot_count: - continue - node_slot_indices.append(slot_idx) - - faces: list[tuple[int, int, int]] = [] - used_batches = 0 - used_slots = 0 - - def append_batch(batch_idx: int) -> None: - nonlocal used_batches - if batch_idx < 0 or batch_idx >= len(batches): - return - idx_count, idx_start, base_vertex, _ = batches[batch_idx] - if idx_count < 3: - return - end = idx_start + idx_count - if end > len(indices): - return - used_batches += 1 - tri_count = idx_count // 3 - for t in range(tri_count): - i0 = indices[idx_start + t * 3 + 0] + base_vertex - i1 = indices[idx_start + t * 3 + 1] + base_vertex - i2 = indices[idx_start + t * 3 + 2] + base_vertex - if i0 >= vertex_count or i1 >= vertex_count or i2 >= vertex_count: - continue - faces.append((i0, i1, i2)) - if len(faces) >= max_faces: - return - - if node_slot_indices: - for slot_idx in node_slot_indices: - if len(faces) >= max_faces: - break - _tri_start, _tri_count, batch_start, slot_batch_count = slots[slot_idx] - used_slots += 1 - for bi in range(batch_start, batch_start + slot_batch_count): - append_batch(bi) - if len(faces) >= max_faces: - break - else: - for bi in range(batch_count): - append_batch(bi) - if len(faces) >= max_faces: - break - - if not faces: - raise RuntimeError("no faces selected for export") - - meta = { - "vertex_count": vertex_count, - "index_count": index_count, - "batch_count": batch_count, - "slot_count": slot_count, - "node_count": node_count, - "used_slots": used_slots, - "used_batches": used_batches, - "face_count": len(faces), - } - return positions, faces, meta - - -def _compute_vertex_normals( - positions: list[tuple[float, float, float]], - faces: list[tuple[int, int, int]], -) -> list[tuple[float, float, float]]: - acc = [[0.0, 0.0, 0.0] for _ in positions] - for i0, i1, i2 in faces: - p0 = positions[i0] - p1 = positions[i1] - p2 = positions[i2] - ux = p1[0] - p0[0] - uy = p1[1] - p0[1] - uz = p1[2] - p0[2] - vx = p2[0] - p0[0] - vy = p2[1] - p0[1] - vz = p2[2] - p0[2] - nx = uy * vz - uz * vy - ny = uz * vx - ux * vz - nz = ux * vy - uy * vx - acc[i0][0] += nx - acc[i0][1] += ny - acc[i0][2] += nz - acc[i1][0] += nx - acc[i1][1] += ny - acc[i1][2] += nz - acc[i2][0] += nx - acc[i2][1] += ny - acc[i2][2] += nz - - normals: list[tuple[float, float, float]] = [] - for nx, ny, nz in acc: - ln = math.sqrt(nx * nx + ny * ny + nz * nz) - if ln <= 1e-12: - normals.append((0.0, 1.0, 0.0)) - else: - normals.append((nx / ln, ny / ln, nz / ln)) - return normals - - -def _write_obj( - output_path: Path, - object_name: str, - positions: list[tuple[float, float, float]], - faces: list[tuple[int, int, int]], -) -> None: - output_path.parent.mkdir(parents=True, exist_ok=True) - normals = _compute_vertex_normals(positions, faces) - - with output_path.open("w", encoding="utf-8", newline="\n") as out: - out.write("# Exported by msh_export_obj.py\n") - out.write(f"o {object_name}\n") - for x, y, z in positions: - out.write(f"v {x:.9g} {y:.9g} {z:.9g}\n") - for nx, ny, nz in normals: - out.write(f"vn {nx:.9g} {ny:.9g} {nz:.9g}\n") - for i0, i1, i2 in faces: - a = i0 + 1 - b = i1 + 1 - c = i2 + 1 - out.write(f"f {a}//{a} {b}//{b} {c}//{c}\n") - - -def cmd_list_models(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - blob = archive_path.read_bytes() - parsed = _parse_nres(blob, str(archive_path)) - rows = [row for row in parsed["entries"] if str(row["name"]).lower().endswith(".msh")] - print(f"Archive: {archive_path}") - print(f"MSH entries: {len(rows)}") - for row in rows: - print(f"- {row['name']}") - return 0 - - -def cmd_export(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - output_path = Path(args.output).resolve() - - model_blob, model_label = _pick_model_payload(archive_path, args.model) - positions, faces, meta = _extract_geometry( - model_blob, - lod=int(args.lod), - group=int(args.group), - max_faces=int(args.max_faces), - all_batches=bool(args.all_batches), - ) - obj_name = Path(model_label).stem or "msh_model" - _write_obj(output_path, obj_name, positions, faces) - - print(f"Exported model : {model_label}") - print(f"Output OBJ : {output_path}") - print(f"Object name : {obj_name}") - print( - "Geometry : " - f"vertices={meta['vertex_count']}, faces={meta['face_count']}, " - f"batches={meta['used_batches']}/{meta['batch_count']}, slots={meta['used_slots']}/{meta['slot_count']}" - ) - print( - "Mode : " - f"lod={args.lod}, group={args.group}, all_batches={bool(args.all_batches)}" - ) - return 0 - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description="Export NGI MSH geometry to Wavefront OBJ." - ) - sub = parser.add_subparsers(dest="command", required=True) - - list_models = sub.add_parser("list-models", help="List .msh entries in an NRes archive.") - list_models.add_argument("--archive", required=True, help="Path to archive (e.g. animals.rlb).") - list_models.set_defaults(func=cmd_list_models) - - export = sub.add_parser("export", help="Export one model to OBJ.") - export.add_argument("--archive", required=True, help="Path to NRes archive or direct model payload.") - export.add_argument( - "--model", - help="Model entry name (*.msh) inside archive. If omitted, first .msh is used.", - ) - export.add_argument("--output", required=True, help="Output .obj path.") - export.add_argument("--lod", type=int, default=0, help="LOD index 0..2 (default: 0).") - export.add_argument("--group", type=int, default=0, help="Group index 0..4 (default: 0).") - export.add_argument("--max-faces", type=int, default=120000, help="Face limit (default: 120000).") - export.add_argument( - "--all-batches", - action="store_true", - help="Ignore slot matrix selection and export all batches.", - ) - export.set_defaults(func=cmd_export) - - return parser - - -def main() -> int: - parser = build_parser() - args = parser.parse_args() - return int(args.func(args)) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/tools/msh_preview_renderer.py b/tools/msh_preview_renderer.py deleted file mode 100644 index 53b4e63..0000000 --- a/tools/msh_preview_renderer.py +++ /dev/null @@ -1,481 +0,0 @@ -#!/usr/bin/env python3 -""" -Primitive software renderer for NGI MSH models. - -Output format: binary PPM (P6), no external dependencies. -""" - -from __future__ import annotations - -import argparse -import math -import struct -from pathlib import Path -from typing import Any - -import archive_roundtrip_validator as arv - -MAGIC_NRES = b"NRes" - - -def _entry_payload(blob: bytes, entry: dict[str, Any]) -> bytes: - start = int(entry["data_offset"]) - end = start + int(entry["size"]) - return blob[start:end] - - -def _parse_nres(blob: bytes, source: str) -> dict[str, Any]: - if blob[:4] != MAGIC_NRES: - raise RuntimeError(f"{source}: not an NRes payload") - return arv.parse_nres(blob, source=source) - - -def _by_type(entries: list[dict[str, Any]]) -> dict[int, list[dict[str, Any]]]: - out: dict[int, list[dict[str, Any]]] = {} - for row in entries: - out.setdefault(int(row["type_id"]), []).append(row) - return out - - -def _pick_model_payload(archive_path: Path, model_name: str | None) -> tuple[bytes, str]: - root_blob = archive_path.read_bytes() - parsed = _parse_nres(root_blob, str(archive_path)) - - msh_entries = [row for row in parsed["entries"] if str(row["name"]).lower().endswith(".msh")] - if msh_entries: - chosen: dict[str, Any] | None = None - if model_name: - model_l = model_name.lower() - for row in msh_entries: - name_l = str(row["name"]).lower() - if name_l == model_l: - chosen = row - break - if chosen is None: - for row in msh_entries: - if str(row["name"]).lower().startswith(model_l): - chosen = row - break - else: - chosen = msh_entries[0] - - if chosen is None: - names = ", ".join(str(row["name"]) for row in msh_entries[:12]) - raise RuntimeError( - f"model '{model_name}' not found in {archive_path}. Available: {names}" - ) - return _entry_payload(root_blob, chosen), str(chosen["name"]) - - # Fallback: treat file itself as a model NRes payload. - by_type = _by_type(parsed["entries"]) - if all(k in by_type for k in (1, 2, 3, 6, 13)): - return root_blob, archive_path.name - - raise RuntimeError( - f"{archive_path} does not contain .msh entries and does not look like a direct model payload" - ) - - -def _get_single(by_type: dict[int, list[dict[str, Any]]], type_id: int, label: str) -> dict[str, Any]: - rows = by_type.get(type_id, []) - if not rows: - raise RuntimeError(f"missing resource type {type_id} ({label})") - return rows[0] - - -def _extract_geometry( - model_blob: bytes, - *, - lod: int, - group: int, - max_faces: int, -) -> tuple[list[tuple[float, float, float]], list[tuple[int, int, int]], dict[str, int]]: - parsed = _parse_nres(model_blob, "<model>") - by_type = _by_type(parsed["entries"]) - - res1 = _get_single(by_type, 1, "Res1") - res2 = _get_single(by_type, 2, "Res2") - res3 = _get_single(by_type, 3, "Res3") - res6 = _get_single(by_type, 6, "Res6") - res13 = _get_single(by_type, 13, "Res13") - - # Positions - pos_blob = _entry_payload(model_blob, res3) - if len(pos_blob) % 12 != 0: - raise RuntimeError(f"Res3 size is not divisible by 12: {len(pos_blob)}") - vertex_count = len(pos_blob) // 12 - positions = [struct.unpack_from("<3f", pos_blob, i * 12) for i in range(vertex_count)] - - # Indices - idx_blob = _entry_payload(model_blob, res6) - if len(idx_blob) % 2 != 0: - raise RuntimeError(f"Res6 size is not divisible by 2: {len(idx_blob)}") - index_count = len(idx_blob) // 2 - indices = list(struct.unpack_from(f"<{index_count}H", idx_blob, 0)) - - # Batches - batch_blob = _entry_payload(model_blob, res13) - if len(batch_blob) % 20 != 0: - raise RuntimeError(f"Res13 size is not divisible by 20: {len(batch_blob)}") - batch_count = len(batch_blob) // 20 - batches: list[tuple[int, int, int, int]] = [] - for i in range(batch_count): - off = i * 20 - # Keep only fields used by renderer: - # indexCount, indexStart, baseVertex - idx_count = struct.unpack_from("<H", batch_blob, off + 8)[0] - idx_start = struct.unpack_from("<I", batch_blob, off + 10)[0] - base_vertex = struct.unpack_from("<I", batch_blob, off + 16)[0] - batches.append((idx_count, idx_start, base_vertex, i)) - - # Slots - res2_blob = _entry_payload(model_blob, res2) - if len(res2_blob) < 0x8C: - raise RuntimeError("Res2 is too small (< 0x8C)") - slot_blob = res2_blob[0x8C:] - if len(slot_blob) % 68 != 0: - raise RuntimeError(f"Res2 slot area is not divisible by 68: {len(slot_blob)}") - slot_count = len(slot_blob) // 68 - slots: list[tuple[int, int, int, int]] = [] - for i in range(slot_count): - off = i * 68 - tri_start, tri_count, batch_start, slot_batch_count = struct.unpack_from("<4H", slot_blob, off) - slots.append((tri_start, tri_count, batch_start, slot_batch_count)) - - # Nodes / slot matrix - res1_blob = _entry_payload(model_blob, res1) - node_stride = int(res1["attr3"]) - node_count = int(res1["attr1"]) - node_slot_indices: list[int] = [] - if node_stride >= 38 and len(res1_blob) >= node_count * node_stride: - if lod < 0 or lod > 2: - raise RuntimeError(f"lod must be 0..2 (got {lod})") - if group < 0 or group > 4: - raise RuntimeError(f"group must be 0..4 (got {group})") - matrix_index = lod * 5 + group - for n in range(node_count): - off = n * node_stride + 8 + matrix_index * 2 - slot_idx = struct.unpack_from("<H", res1_blob, off)[0] - if slot_idx == 0xFFFF: - continue - if slot_idx >= slot_count: - continue - node_slot_indices.append(slot_idx) - - # Build triangle list. - faces: list[tuple[int, int, int]] = [] - used_batches = 0 - used_slots = 0 - - def append_batch(batch_idx: int) -> None: - nonlocal used_batches - if batch_idx < 0 or batch_idx >= len(batches): - return - idx_count, idx_start, base_vertex, _ = batches[batch_idx] - if idx_count < 3: - return - end = idx_start + idx_count - if end > len(indices): - return - used_batches += 1 - tri_count = idx_count // 3 - for t in range(tri_count): - i0 = indices[idx_start + t * 3 + 0] + base_vertex - i1 = indices[idx_start + t * 3 + 1] + base_vertex - i2 = indices[idx_start + t * 3 + 2] + base_vertex - if i0 >= vertex_count or i1 >= vertex_count or i2 >= vertex_count: - continue - faces.append((i0, i1, i2)) - if len(faces) >= max_faces: - return - - if node_slot_indices: - for slot_idx in node_slot_indices: - if len(faces) >= max_faces: - break - _tri_start, _tri_count, batch_start, slot_batch_count = slots[slot_idx] - used_slots += 1 - for bi in range(batch_start, batch_start + slot_batch_count): - append_batch(bi) - if len(faces) >= max_faces: - break - else: - # Fallback if slot matrix is unavailable: draw all batches. - for bi in range(batch_count): - append_batch(bi) - if len(faces) >= max_faces: - break - - meta = { - "vertex_count": vertex_count, - "index_count": index_count, - "batch_count": batch_count, - "slot_count": slot_count, - "node_count": node_count, - "used_slots": used_slots, - "used_batches": used_batches, - "face_count": len(faces), - } - if not faces: - raise RuntimeError("no faces selected for rendering") - return positions, faces, meta - - -def _write_ppm(path: Path, width: int, height: int, rgb: bytearray) -> None: - path.parent.mkdir(parents=True, exist_ok=True) - with path.open("wb") as handle: - handle.write(f"P6\n{width} {height}\n255\n".encode("ascii")) - handle.write(rgb) - - -def _render_software( - positions: list[tuple[float, float, float]], - faces: list[tuple[int, int, int]], - *, - width: int, - height: int, - yaw_deg: float, - pitch_deg: float, - wireframe: bool, -) -> bytearray: - xs = [p[0] for p in positions] - ys = [p[1] for p in positions] - zs = [p[2] for p in positions] - cx = (min(xs) + max(xs)) * 0.5 - cy = (min(ys) + max(ys)) * 0.5 - cz = (min(zs) + max(zs)) * 0.5 - span = max(max(xs) - min(xs), max(ys) - min(ys), max(zs) - min(zs)) - radius = max(span * 0.5, 1e-3) - - yaw = math.radians(yaw_deg) - pitch = math.radians(pitch_deg) - cyaw = math.cos(yaw) - syaw = math.sin(yaw) - cpitch = math.cos(pitch) - spitch = math.sin(pitch) - - camera_dist = radius * 3.2 - scale = min(width, height) * 0.95 - - # Transform all vertices once. - vx: list[float] = [] - vy: list[float] = [] - vz: list[float] = [] - sx: list[float] = [] - sy: list[float] = [] - for x, y, z in positions: - x0 = x - cx - y0 = y - cy - z0 = z - cz - x1 = cyaw * x0 + syaw * z0 - z1 = -syaw * x0 + cyaw * z0 - y2 = cpitch * y0 - spitch * z1 - z2 = spitch * y0 + cpitch * z1 + camera_dist - if z2 < 1e-3: - z2 = 1e-3 - vx.append(x1) - vy.append(y2) - vz.append(z2) - sx.append(width * 0.5 + (x1 / z2) * scale) - sy.append(height * 0.5 - (y2 / z2) * scale) - - rgb = bytearray([16, 18, 24] * (width * height)) - zbuf = [float("inf")] * (width * height) - light_dir = (0.35, 0.45, 1.0) - l_len = math.sqrt(light_dir[0] ** 2 + light_dir[1] ** 2 + light_dir[2] ** 2) - light = (light_dir[0] / l_len, light_dir[1] / l_len, light_dir[2] / l_len) - - def edge(ax: float, ay: float, bx: float, by: float, px: float, py: float) -> float: - return (px - ax) * (by - ay) - (py - ay) * (bx - ax) - - for i0, i1, i2 in faces: - x0 = sx[i0] - y0 = sy[i0] - x1 = sx[i1] - y1 = sy[i1] - x2 = sx[i2] - y2 = sy[i2] - area = edge(x0, y0, x1, y1, x2, y2) - if area == 0.0: - continue - - # Shading from camera-space normal. - ux = vx[i1] - vx[i0] - uy = vy[i1] - vy[i0] - uz = vz[i1] - vz[i0] - wx = vx[i2] - vx[i0] - wy = vy[i2] - vy[i0] - wz = vz[i2] - vz[i0] - nx = uy * wz - uz * wy - ny = uz * wx - ux * wz - nz = ux * wy - uy * wx - n_len = math.sqrt(nx * nx + ny * ny + nz * nz) - if n_len > 0.0: - nx /= n_len - ny /= n_len - nz /= n_len - intensity = nx * light[0] + ny * light[1] + nz * light[2] - if intensity < 0.0: - intensity = 0.0 - shade = int(45 + 200 * intensity) - color = (shade, shade, min(255, shade + 18)) - - minx = int(max(0, math.floor(min(x0, x1, x2)))) - maxx = int(min(width - 1, math.ceil(max(x0, x1, x2)))) - miny = int(max(0, math.floor(min(y0, y1, y2)))) - maxy = int(min(height - 1, math.ceil(max(y0, y1, y2)))) - if minx > maxx or miny > maxy: - continue - - z0 = vz[i0] - z1 = vz[i1] - z2 = vz[i2] - - for py in range(miny, maxy + 1): - fy = py + 0.5 - row = py * width - for px in range(minx, maxx + 1): - fx = px + 0.5 - w0 = edge(x1, y1, x2, y2, fx, fy) - w1 = edge(x2, y2, x0, y0, fx, fy) - w2 = edge(x0, y0, x1, y1, fx, fy) - if area > 0: - if w0 < 0 or w1 < 0 or w2 < 0: - continue - else: - if w0 > 0 or w1 > 0 or w2 > 0: - continue - inv_area = 1.0 / area - bz0 = w0 * inv_area - bz1 = w1 * inv_area - bz2 = w2 * inv_area - depth = bz0 * z0 + bz1 * z1 + bz2 * z2 - idx = row + px - if depth >= zbuf[idx]: - continue - zbuf[idx] = depth - p = idx * 3 - rgb[p + 0] = color[0] - rgb[p + 1] = color[1] - rgb[p + 2] = color[2] - - if wireframe: - def draw_line(xa: float, ya: float, xb: float, yb: float) -> None: - x0i = int(round(xa)) - y0i = int(round(ya)) - x1i = int(round(xb)) - y1i = int(round(yb)) - dx = abs(x1i - x0i) - sx_step = 1 if x0i < x1i else -1 - dy = -abs(y1i - y0i) - sy_step = 1 if y0i < y1i else -1 - err = dx + dy - x = x0i - y = y0i - while True: - if 0 <= x < width and 0 <= y < height: - p = (y * width + x) * 3 - rgb[p + 0] = 240 - rgb[p + 1] = 245 - rgb[p + 2] = 255 - if x == x1i and y == y1i: - break - e2 = 2 * err - if e2 >= dy: - err += dy - x += sx_step - if e2 <= dx: - err += dx - y += sy_step - - for i0, i1, i2 in faces: - draw_line(sx[i0], sy[i0], sx[i1], sy[i1]) - draw_line(sx[i1], sy[i1], sx[i2], sy[i2]) - draw_line(sx[i2], sy[i2], sx[i0], sy[i0]) - - return rgb - - -def cmd_list_models(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - blob = archive_path.read_bytes() - parsed = _parse_nres(blob, str(archive_path)) - rows = [row for row in parsed["entries"] if str(row["name"]).lower().endswith(".msh")] - print(f"Archive: {archive_path}") - print(f"MSH entries: {len(rows)}") - for row in rows: - print(f"- {row['name']}") - return 0 - - -def cmd_render(args: argparse.Namespace) -> int: - archive_path = Path(args.archive).resolve() - output_path = Path(args.output).resolve() - - model_blob, model_label = _pick_model_payload(archive_path, args.model) - positions, faces, meta = _extract_geometry( - model_blob, - lod=int(args.lod), - group=int(args.group), - max_faces=int(args.max_faces), - ) - rgb = _render_software( - positions, - faces, - width=int(args.width), - height=int(args.height), - yaw_deg=float(args.yaw), - pitch_deg=float(args.pitch), - wireframe=bool(args.wireframe), - ) - _write_ppm(output_path, int(args.width), int(args.height), rgb) - - print(f"Rendered model: {model_label}") - print(f"Output : {output_path}") - print( - "Geometry : " - f"vertices={meta['vertex_count']}, faces={meta['face_count']}, " - f"batches={meta['used_batches']}/{meta['batch_count']}, slots={meta['used_slots']}/{meta['slot_count']}" - ) - print(f"Mode : lod={args.lod}, group={args.group}, wireframe={bool(args.wireframe)}") - return 0 - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser( - description="Primitive NGI MSH renderer (software, dependency-free)." - ) - sub = parser.add_subparsers(dest="command", required=True) - - list_models = sub.add_parser("list-models", help="List .msh entries in an NRes archive.") - list_models.add_argument("--archive", required=True, help="Path to archive (e.g. animals.rlb).") - list_models.set_defaults(func=cmd_list_models) - - render = sub.add_parser("render", help="Render one model to PPM image.") - render.add_argument("--archive", required=True, help="Path to NRes archive or direct model payload.") - render.add_argument( - "--model", - help="Model entry name (*.msh) inside archive. If omitted, first .msh is used.", - ) - render.add_argument("--output", required=True, help="Output .ppm file path.") - render.add_argument("--lod", type=int, default=0, help="LOD index 0..2 (default: 0).") - render.add_argument("--group", type=int, default=0, help="Group index 0..4 (default: 0).") - render.add_argument("--max-faces", type=int, default=120000, help="Face limit (default: 120000).") - render.add_argument("--width", type=int, default=1280, help="Image width (default: 1280).") - render.add_argument("--height", type=int, default=720, help="Image height (default: 720).") - render.add_argument("--yaw", type=float, default=35.0, help="Yaw angle in degrees (default: 35).") - render.add_argument("--pitch", type=float, default=18.0, help="Pitch angle in degrees (default: 18).") - render.add_argument("--wireframe", action="store_true", help="Draw white wireframe overlay.") - render.set_defaults(func=cmd_render) - - return parser - - -def main() -> int: - parser = build_parser() - args = parser.parse_args() - return int(args.func(args)) - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/unpacker/Cargo.toml b/unpacker/Cargo.toml new file mode 100644 index 0000000..adb64ec --- /dev/null +++ b/unpacker/Cargo.toml @@ -0,0 +1,9 @@ +[package] +name = "unpacker" +version = "0.1.1" +edition = "2021" + +[dependencies] +byteorder = "1.4.3" +serde = { version = "1.0.160", features = ["derive"] } +serde_json = "1.0.96" diff --git a/unpacker/README.md b/unpacker/README.md new file mode 100644 index 0000000..2c6be02 --- /dev/null +++ b/unpacker/README.md @@ -0,0 +1,41 @@ +# NRes Game Resource Unpacker + +At the moment, this is a demonstration of the NRes game resource unpacking algorithm in action. +It unpacks 100% of the NRes game resources for the game "Parkan: Iron Strategy". +The unpacked resources can be packed again using the [packer](../packer) utility and replace the original game files. + +__Attention!__ +This is a test version of the utility. +It overwrites existing files without asking. + +## Building + +To build the tools, you need to run the following command in the root directory: + +```bash +cargo build --release +``` + +## Running + +You can run the utility with the following command: + +```bash +./target/release/unpacker /path/to/file.ex /path/to/output +``` + +- `/path/to/file.ex`: This is the file containing the game resources that will be unpacked. +- `/path/to/output`: This is the directory where the unpacked files will be placed. + +## How it Works + +The structure describing the packed game resources is not fully understood yet. +Therefore, the utility saves unpacked files in the format `file_name.file_index` because some files have the same name. + +Additionally, an `index.json` file is created, which is important for re-packing the files. +This file lists all the fields that game resources have in their packed form. +It is essential to preserve the file index for the game to function correctly, as the game engine looks for the necessary files by index. + +Files can be replaced and packed back using the [packer](../packer). +The newly obtained game resource files are correctly processed by the game engine. +For example, sounds and 3D models of warbots' weapons were successfully replaced. diff --git a/unpacker/src/main.rs b/unpacker/src/main.rs new file mode 100644 index 0000000..2a84688 --- /dev/null +++ b/unpacker/src/main.rs @@ -0,0 +1,124 @@ +use std::env; +use std::fs::File; +use std::io::{BufReader, BufWriter, Read, Seek, SeekFrom, Write}; + +use byteorder::{ByteOrder, LittleEndian}; +use serde::{Deserialize, Serialize}; + +#[derive(Serialize, Deserialize, Debug)] +pub struct FileHeader { + pub size: u32, + pub total: u32, + pub type1: u32, + pub type2: u32, +} + +#[derive(Serialize, Deserialize, Debug)] +pub struct ListElement { + pub extension: String, + pub index: u32, + pub name: String, + #[serde(skip_serializing)] + pub position: u32, + #[serde(skip_serializing)] + pub size: u32, + pub unknown0: u32, + pub unknown1: u32, + pub unknown2: u32, +} + +fn main() { + let args: Vec<String> = env::args().collect(); + + let input = &args[1]; + let output = &args[2]; + + unpack(String::from(input), String::from(output)); +} + +fn unpack(input: String, output: String) { + let file = File::open(input).unwrap(); + let metadata = file.metadata().unwrap(); + + let mut reader = BufReader::new(file); + let mut list: Vec<ListElement> = Vec::new(); + + // Считываем заголовок файла + let mut header_buffer = [0u8; 16]; + reader.seek(SeekFrom::Start(0)).unwrap(); + reader.read_exact(&mut header_buffer).unwrap(); + + let file_header = FileHeader { + size: LittleEndian::read_u32(&header_buffer[12..16]), + total: LittleEndian::read_u32(&header_buffer[8..12]), + type1: LittleEndian::read_u32(&header_buffer[0..4]), + type2: LittleEndian::read_u32(&header_buffer[4..8]), + }; + + if file_header.type1 != 1936020046 || file_header.type2 != 256 { + panic!("this isn't NRes file"); + } + + if metadata.len() != file_header.size as u64 { + panic!("incorrect size") + } + + // Считываем список файлов + let list_files_start_position = file_header.size - (file_header.total * 64); + let list_files_size = file_header.total * 64; + + let mut list_buffer = vec![0u8; list_files_size as usize]; + reader + .seek(SeekFrom::Start(list_files_start_position as u64)) + .unwrap(); + reader.read_exact(&mut list_buffer).unwrap(); + + if list_buffer.len() % 64 != 0 { + panic!("invalid files list") + } + + for i in 0..(list_buffer.len() / 64) { + let from = i * 64; + let to = (i * 64) + 64; + let chunk: &[u8] = &list_buffer[from..to]; + + let element_list = ListElement { + extension: String::from_utf8_lossy(&chunk[0..4]) + .trim_matches(char::from(0)) + .to_string(), + index: LittleEndian::read_u32(&chunk[60..64]), + name: String::from_utf8_lossy(&chunk[20..56]) + .trim_matches(char::from(0)) + .to_string(), + position: LittleEndian::read_u32(&chunk[56..60]), + size: LittleEndian::read_u32(&chunk[12..16]), + unknown0: LittleEndian::read_u32(&chunk[4..8]), + unknown1: LittleEndian::read_u32(&chunk[8..12]), + unknown2: LittleEndian::read_u32(&chunk[16..20]), + }; + + list.push(element_list) + } + + // Распаковываем файлы в директорию + for element in &list { + let path = format!("{}/{}.{}", output, element.name, element.index); + let mut file = File::create(path).unwrap(); + + let mut file_buffer = vec![0u8; element.size as usize]; + reader + .seek(SeekFrom::Start(element.position as u64)) + .unwrap(); + reader.read_exact(&mut file_buffer).unwrap(); + + file.write_all(&file_buffer).unwrap(); + file_buffer.clear(); + } + + // Выгрузка списка файлов в JSON + let path = format!("{}/{}", output, "index.json"); + let file = File::create(path).unwrap(); + let mut writer = BufWriter::new(file); + serde_json::to_writer_pretty(&mut writer, &list).unwrap(); + writer.flush().unwrap(); +} |