Crate structure

← Back to docs · Architecture · Module development guide

This page is a map for someone who is about to change the code. The architecture page has the full crate table and the dependency graph. Here you find where things live.

Welkin is a Cargo workspace of 25 crates, edition 2024, Rust 1.88 or later. welkin-companion (a Tauri desktop app) lives beside them and builds separately. Two crates produce programs: welkin-region and welkin-robust.

Layers

LayerCratesRole
Corewelkin-types, welkin-llsd, welkin-msg, welkin-config, welkin-runtimeTypes, LLSD and LLUDP codecs, TOML config, logging
Networkwelkin-net, welkin-capsUDP server and circuits, HTTP capabilities, event queues
Scenewelkin-scene, welkin-prim, welkin-modulesScene graph, terrain, prim meshing, region modules
Physicswelkin-physics, welkin-physics-rapierPhysics traits and the Rapier 3D backend
Scriptingwelkin-script-compiler, welkin-script-vm, welkin-script-apiLSL to Luau, the VM and builtins, constant tables
Serviceswelkin-services, welkin-dataGrid service handlers, remote connectors, SQL stores
Archiveswelkin-archive, welkin-migrationOAR and IAR, C# migration tools
Testingwelkin-conformance, welkin-capacity, welkin-realmwalkerReplay, benchmarks, bot SDK
Binarieswelkin-region, welkin-robustThe two programs
Scaffoldwelkin-portalWeb portal; no other crate depends on it and no binary mounts it

Where to look

In welkin-region/src/, the region simulator:

AreaFiles
Packet loop and startupmain.rs
Console and admin APIconsole.rs, console_io.rs
Saving and loadingpersist.rs, persist_load.rs, script_persist.rs, region_identity.rs
Estate and permissionsestate_config.rs
Objects and inventoryobject_add.rs, inventory_rez.rs, attachments_io.rs, scene_sync.rs
Movement and physicsavatar_move.rs, physics_cmd.rs
Terrainterraform.rs
Soundsound_io.rs
Groupsgroups_io.rs, groups_queries.rs, groups_admin.rs, groups_invites.rs, groups_chat.rs, groups_queue.rs, groups_tasks.rs

Elsewhere:

AreaWhere
Scene graph, objects, attachmentswelkin-scene/src/scene.rs, group.rs, part.rs
Terrain heights, brushes, LayerData encoderwelkin-scene/src/terrain*.rs
Object XML (XML2)welkin-scene/src/xml2.rs
The RegionModule trait and registrywelkin-modules/src/module.rs, registry.rs
The ClientEgress trait and test doubleswelkin-modules/src/egress.rs
Grid services (login, accounts, groups and others)welkin-services/src/
Clients for those services, used by the regionwelkin-services/src/remote/
SQL stores and migrationswelkin-data/src/
Builtin LSL functionswelkin-script-vm/src/builtins/

Rules the code follows

  • Handlers do real work. CI fails on todo!(), unimplemented!(), STUB and PLACEHOLDER under crates/.
  • A viewer packet acts for the authenticated avatar of the connection, never for an agent ID the packet claims.
  • Code that waits on another service does not hold the session lock.
  • Features are wired into a running binary. A tested module that nothing calls does not count as done.