Aether puts a Windows game in front of files that are not on disk. Two small Windows programs do it:
aether-injector.exe(crateaether-inject): starts the game's process and loads the shim into it by remote-thread injection.aether_shim.dll(crateaether-shim, hooks inaether-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.
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\releaseThe 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).
cargo test --no-fail-fastWindows 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).
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.
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.
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.
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.
GPL-3.0-or-later (LICENSE).