Synvael

A voxel RPG sandbox survival game set in Sylenor, a medieval fantasy world bound together by twelve magical elements and slowly being unravelled by a thirteenth.

Half-metre voxels, Souls-like combat with severable limbs, and an elemental magic wheel that punishes overuse. Written in Rust and Vulkan, with gameplay logic in Lua through the same modding API the base game is built on: JSON data packs for content, Lua mods for behaviour, and resource packs for textures and sound.

Important

The canonical repository is git.cryoforgenexus.com/Synvael/synvael. GitHub is a mirror; issues, pull requests, CI, and the CLA check all live on the canonical repository.

Warning

Pre-Alpha. The wire protocol, save records, content IDs, Lua API, and crate boundaries all change without notice, and there is no migration path until a format version increments. What runs today is the code that exists. Everything else is intent.

🌍 Design targets

None of this is implemented yet. The generator currently produces Perlin terrain and nothing else.

• Three vertical layers. One map location carries a surface biome, a cave biome below, and a floating island biome above, each with its own flora, fauna, magic field, and weather.
• Grandiose scale. Signature trees clear 32 m, mountain ranges form ridges, and crossing a biome is a journey, with a target view distance of 8 km through a LOD ladder. Twelve Primordials, one per element, roam the world at a size that reshapes the terrain they cross. Rivers need a source, a mouth, and a downhill gradient between them, water with nowhere to go pools into lakes, and flow varies with snowmelt at the source.
• A world that keeps running. Forests grow, seed, age, self-thin, and recover from fire. Wildlife runs the same cycle, and vegetation density caps herbivores the way prey caps predators.
• The Corruption. A hive organism seeded at worldgen that grows, builds, and spreads if nothing stops it. It is the central threat of the world.
• Body-part damage. Damage routes to head, torso, arms, and legs, each tracking Healthy through Damaged, Broken, and Severed. Slashing weapons cut broken limbs into world items. The HUD is a paper doll, not a health bar.
• The magic wheel. Twelve elements in six opposing pairs. An element's position on the wheel scales its spells and penalises its opposite; a balanced wheel just regenerates faster. Casting too far in one direction overloads.
• Weight to movement. Everything above walking costs a wind-up, a locked state, or stamina, and air control is near zero. Mantling and climbing need free hands, so traversal depends on limb state.
• Survival chemistry. A voxel-level pass handles ignition, freezing, steam, gas, current, and thermal spread, feeding body temperature and a hunger/thirst/stamina metabolism.
• A physical interface. Pixel art on a 960 x 540 canvas at integer scale, animated on a fixed 12 fps step. No minimap, clock, compass, or coordinate readout: every overlay is an instrument the player found and equipped. First or third person out of combat, third person only once a weapon is drawn.
• Modding in three layers. Blocks, items, recipes, loot tables, and biomes are declarative JSON, so a data pack registers content without writing a line of Lua. Lua mods cover behaviour: spells, mob AI, movesets, stances. Resource packs override textures, sounds, models, and fonts client-side, and a server can push one cosmetic overlay of its own. Everything scopes per world rather than per launcher profile, and mods are always free (packs, ADR-0007).

🔭 What runs today

Subsystem	State
Rendering	Vulkan 1.3 dynamic rendering through ash, GLSL compiled to SPIR-V at build time, CPU greedy meshing on a worker pool, frustum culling, debug wireframe and vertex-point modes.
Worldgen	Seed-deterministic Perlin terrain from a pinned noise version, tuned by assets/data/worldgen/default/ (ADR-0003).
Simulation	Authoritative bevy_ecs server on a 20 Hz tick, movement stepped at 60 Hz, with tick-budget reporting.
Chunk streaming	Residency reconciled against the union of every client's subscription cylinder, generated off-tick, delivered under a per-tick budget.
Persistence	SYNW world metadata plus SYNR/SYNC region files holding baseline-relative sparse edits, flushed by a single save actor (ADR-0009).
Networking	QUIC through quinn, versioned handshake, trust-on-first-use certificate pinning, separate input/authority/chunk streams (ADR-0010, ADR-0011).
Movement	Fixed-timestep kinematic controller, swept AABB collision, seven-state stance machine, auto-step, client prediction and replay reconciliation (ADR-0013).
Diagnostics	GPU, host, network, chunk, frame, and server-tick statistics in an in-client panel and the dedicated server log.
Scripting	Not started. crates/scripting is an empty placeholder.

Still ahead: LOD tiers, GPU meshing, palette compression, block breaking and placement, texturing, and every gameplay system.

🚀 Getting started

You need a Rust stable toolchain, Git LFS, a Vulkan-capable GPU on Linux or Windows, and libshaderc (libshaderc-dev on Debian, shaderc on Arch, or the Vulkan SDK on Windows). Without libshaderc the build compiles it from source, which also needs a C++ toolchain, CMake, Python 3, and Ninja. macOS, mobile, consoles, and web are out of scope.

git clone https://git.cryoforgenexus.com/Synvael/synvael.git
cd synvael
git lfs pull
cargo build

The client dials a server and cannot host one in-process yet, so start the server first. Run both from the repository root, since asset paths resolve relative to the working directory.

cargo run --release -p server    # binds 127.0.0.1:25565, pre-warms the spawn region
cargo run --release -p client    # opens the window and connects

Debug builds work (the dev profile optimises dependencies while keeping the overflow checks that chunk-index arithmetic relies on), but worldgen and meshing are heavy enough that anything past a smoke test wants --release.

Controls

WASD to move, mouse to look, Space to jump, Left Shift to sprint, Left Ctrl to crouch, Left Alt to walk, Escape to quit.

Debug affordances sit behind an F1 chord so they cannot collide with movement: F1 + I for the statistics panel, F1 + V for vertex points, F1 + B for triangle edges, F1 + P to force a visible prediction correction. Add Shift to drop the filled pass and leave debug geometry against the clear colour.

Testing and linting

CI enforces all of these. Run them before pushing.

cargo test --workspace
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
stylua --check assets/scripts/ mods/
selene assets/scripts/ mods/

The workspace opts into Clippy's pedantic group and bans unwrap, expect, and the print macros outside main and tests.

📦 Layout

Six crates under crates/:

Crate	Kind	Responsibility
client	binary	Windowing, input, camera, presentation. No simulation logic.
server	binary	Authoritative simulation: streaming, chunk cache, persistence, player state.
shared	library	Protocol and core types: voxels, chunks, worldgen, movement, save records, paths.
renderer	library	Vulkan backend and CPU meshing, decoupled from windowing.
net	library	QUIC transport, connection lifecycle, wire framing. Owns the async runtime.
scripting	library	Lua embedding and modding API. Stubbed.

Content sits outside them: assets/data/ for declarative content, assets/scripts/ for base-game Lua, assets/shaders/ for GLSL, mods/ for example mods and fixtures, docs/ for subsystem notes and ADRs.

Saves and player-installed mods resolve at runtime under the per-user data directory ($XDG_DATA_HOME/synvael on Linux, %APPDATA%\Cryoforge Nexus\Synvael\data on Windows). No path is hard-coded.

The stack is ash (Vulkan 1.3), bevy_ecs, winit, glam, quinn with rustls, serde and postcard, zstd, crossbeam-channel, and tracing. mlua and rapier3d are targets, not yet dependencies. The character controller stays outside rapier3d on purpose: a rigid-body solver is neither deterministic nor replayable under reconciliation.

📖 Documentation

To find out	Read
Rules that apply to every change	DEVELOPMENT.md
How a subsystem works	docs/, plus cargo doc --workspace --open
Why a hard-to-reverse choice was made	docs/adr/
How to contribute	CONTRIBUTING.md
Contributor License Agreement terms	CLA.md
Expected conduct in project spaces	CODE_OF_CONDUCT.md
Who has contributed	CREDITS.md
License terms for code and assets	LICENSE.md
Engineering context for AI coding agents	AGENTS.md

🤝 Contributing

Contributions are welcome and credited. Synvael is open-source but commercially developed by Cryoforge Nexus, and the terms that follow from that (contributor tiers, the required CLA, and what is and is not accepted) are set out in CONTRIBUTING.md. Read it before opening a pull request.

Work happens on dev; main carries releases. Commits follow Conventional Commits with a crate scope (feat(scripting): ...). Participation is governed by the Code of Conduct.

📜 License

Source code is AGPL-3.0-only. Assets under assets/ are CC-BY-NC-SA 4.0, which permits non-commercial resource packs built from them. The exception is assets/scripts/, which is source code and falls under the AGPL. Full terms are in LICENSE.md.

Copyright © 2026 Cryoforge Nexus.