Skip to content
Nexus-ModsPublic

About

Aether: the in-game shim and injector that serve a game's files from a director over shared memory

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Aether

Aether puts a Windows game in front of files that are not on disk. Two small Windows programs do it:

  • aether-injector.exe (crate aether-inject): starts the game's process and loads the shim into it by remote-thread injection.
  • aether_shim.dll (crate aether-shim, hooks in aether-hooks): runs inside the game and detours its NT file and registry calls, answering every operation on a managed path from a director over a shared-memory ring.

The director, the program that decides what the game sees, is not here: it is whatever speaks the wire contract (aether-ipc, aether-protocol), in any language. Running a Windows game on Linux or macOS (Proton, Wine prefixes, CrossOver) is the director's job too; the injector and the shim are the same Windows binaries everywhere, running inside Wine there.

Both ship for x64 and x86 (32-bit games and tools), with the C runtime linked in (+crt-static): the shim loads inside the game, where Windows doesn't look beside it for vcruntime140.dll, and a PC may have no VC++ runtime. They are staged as aether-injector.exe, aether_shim.dll, aether-injector32.exe and aether_shim32.dll.

Writing a director: docs/wire.md, the wire contract byte by byte. How it fits together: docs/architecture.md; the rules the hooks keep: docs/shim-invariants.md.

Build

On Windows, with the MSVC C++ build tools (the Rust toolchain and the i686-pc-windows-msvc target come from rust-toolchain.toml):

rustup toolchain install
powershell -ExecutionPolicy Bypass -File bin\build-natives.ps1             # the four natives, into target\natives
powershell -ExecutionPolicy Bypass -File bin\build-natives.ps1 -Fixtures   # also the test fixtures and the host-target
                                                                           # injector and shim, into target\release

The four are built in Cargo.toml's natives-lto profile (release with fat LTO and one codegen unit: smaller, and no slower per call); everything else, the fixtures among them, in release. Options: -Out <dir> stages the natives elsewhere; -RequireDumpbin fails (rather than warns) when Visual Studio's dumpbin isn't found for the check that none of the four imports the VC++ runtime (on by default when $env:CI is set). bin\natives-key.ps1 prints the natives key, the hash of what the four are built from; it leaves out the crates no native depends on (the fixtures, the test kit, aether-conform, aether-refdirector, aether-filering, aether-fuzz, aether-shimbench), and bin\natives-key.tests.ps1 checks with cargo tree that neither native's dependency tree holds any of them.

On Linux and macOS, bin/build-windows [--release] cross-builds the same natives and the fixtures with cargo-xwin, clang and lld (LLVM 19 or later: the i686 shim's EXPORTAS export needs it).

Test

cargo test --no-fail-fast

Windows is where all of it builds and runs; the portable crates also build and test on Linux (CI's linux job lists them). CI also runs cargo fmt --all --check and cargo clippy --all-targets -- -D warnings (.github/workflows/ci.yml).

When TMP/TEMP contain an 8.3 short-name alias (a ~, as in C:\Users\LONGNA~1\AppData\Local\Temp), eleven of these tests fail. Point them at a path without one first:

$env:TMP = 'C:\vfstmp'; $env:TEMP = 'C:\vfstmp'

Tests whose prerequisite is missing (a fixture not built) skip; with VFS_TEST_REQUIRE_ALL=1 a skip is a failure. The fixtures must be built first (cargo build of the inject artifacts, as ci.yml does).

Benchmarks and fuzzing

What the shim costs a call, what a director costs per opcode, the micro-benchmarks, the counted cost record (costs.txt) that every push checks, and the fuzz targets are described in docs/benchmarks.md. cargo run --release -p aether-shimbench times Win32 calls natively and under the shim, aether-conform bench times a director, and the manual bench workflow compares a base commit with the head on one runner.

Crates

The ones that ship:

Crate Role
aether-inject The injector: starts the target, injects the shim (the aether-injector binary)
aether-shim The shim DLL: DllMain bootstrap
aether-hooks The NT detours and the director client
aether-ipc The shared-memory control ring and bulk arena, OS-free
aether-protocol Wire codecs, opcodes, statuses, open flags, RootId, the shim's bootstrap config
aether-rpc Typed ring ends: the client the shim calls the director with, and the Director trait a director implements
aether-redirect Pure path core: root map, canonicalisation, vpath normalization, DOS wildcards, final names
aether-casefold The case fold names cross the ring in (file paths and registry keys)
aether-ntlayout Pure NT byte layouts and decisions for the hooks
aether-registry Registry overlay tree and its merge with a real key
aether-win Windows shared memory, events and volume lookups
aether-pe Pure PE byte parsing
aether-env Every VFS_* environment switch, defined once

The test fixtures, Windows programs the tests run under the shim, are three crates. aether-fixtures holds seven programs and the library they share: aether-fixture-read (reads a virtual file), -writepath (the write path), -escape (paths that try to escape the managed root), -prefs (the INI profile API), -steam, -nvapi and -registry (probes for the Proton path and the registry overlay). aether-fixture-vproxy and aether-fixture-staticimp are a statically imported proxy DLL and the program that imports it (pre-init injection); staticimp links vproxy's import library, so vproxy is built first, in a cargo invocation of its own (cargo#6313). aether-testkit holds helpers shared by the tests.

Directors live outside this repository. The shim's tests run against a director in memory (crates/aether-hooks/tests/fakedirector), built on aether-refdirector: the reference director, which answers every file and registry opcode, and a null one that answers each with the smallest valid reply, to measure the ring alone. aether-filering maps a ring in a file on any OS, the Wine arrangement of docs/wire.md 2.10 for a native tool.

panic = "unwind" throughout (aether-protocol/tests/unwind.rs pins it). The vendored retour in vendor/ limits its "win64" hooks to x86-64 so the shim builds for i686. CHANGELOG.md lists what each release changes.

Releases

A tag v<semver> makes a release (release.yml) with natives.zip (the four natives), fixtures.zip (the test fixtures and the host-target injector and shim), aether-conform-windows-x64.zip and aether-conform-linux-x64.tar.gz (the conformance tool, unsigned: see "Checking a director"), contract.zip (contract/artifacts.json, contract/env.json, contract/protocol.json, the protocol's golden vectors and contract/scenarios/, the conformance scenarios), natives-key.txt and SHA256SUMS. Check a download with sha256sum -c SHA256SUMS, and the natives' signatures with bin\check-signatures.ps1 -Path <files> -Signer 'CN=Black Tree Gaming Ltd, O=Black Tree Gaming Ltd, L=Exeter, C=GB'.

A tag without a - is a full release, and its natives are signed (SSL.com eSigner, bin/sign.ps1). A tag with one (v0.2.0-rc.1) is a prerelease for testing, with unsigned natives unless a manual run asks for signing. When an earlier full release has the same natives key, its signed natives are reused byte for byte, so a release that changes no native signs nothing. bin\sign.tests.ps1 tests the signing script against fake tools.

Checking a director

aether-conform plays the scenarios of contract/scenarios/ against a director and compares every answer with the one the contract gives. Every release carries it for Windows (aether-conform-windows-x64.zip) and Linux (aether-conform-linux-x64.tar.gz), unsigned, since it is a test tool that is never loaded into a game, and the scenarios are in contract.zip. Unpack both, then:

aether-conform run --director "<your adapter command>" --scenarios scenarios

The adapter is a small program you write that mounts a scenario's tree in your director and tells the run which ring to attach to; the adapter protocol, what a run checks and where the contract lets directors differ are in docs/conformance.md. --malformed also sends requests that are not valid ones, and --generate plays generated trees and operation sequences (--cases, --seed), shrinking and saving the first failure as a scenario file you can replay. aether-conform reference-adapter is the reference director behind an adapter, a working example. aether-conform bench times a director on contract/workloads/ (docs/benchmarks.md). To build it from source: cargo build --release -p aether-conform.

License

GPL-3.0-or-later (LICENSE).

About

Aether: the in-game shim and injector that serve a game's files from a director over shared memory

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages