Quick start
← Back to docs · Architecture · Configuration reference
Requirements
- Rust 1.88 or later (edition 2024)
- SQLite (MariaDB and PostgreSQL are supported in the code but not yet verified)
- A viewer: Aurora Viewer or Firestorm (OpenSim build)
Build
git clone https://github.com/FlintWave/welkin.git
cd welkin
cargo build --workspace --release
This produces two binaries in target/release/:
welkin-robustruns the grid services (login, inventory, assets, grid registry)welkin-regionruns the region simulator (scene, physics, scripting, viewer connections)
Configure
Welkin uses TOML configuration files. A minimal setup needs two:
robust.toml (grid services):
[DatabaseService]
ConnectionString = "sqlite:robust.db?mode=rwc"
welkin.toml (region simulator):
[Region]
RegionName = "Test Region"
RegionLocX = 1000
RegionLocY = 1000
[Network]
ExternalHostName = "127.0.0.1"
InternalPort = 9000
[DatabaseService]
RegionConnectionString = "sqlite:region.db?mode=rwc"
RobustConnectionString = "sqlite:robust.db?mode=rwc"
[GridService]
GridServerURI = "http://127.0.0.1:8003"
[Scene]
PhysicsEnabled = true
ScriptsEnabled = true
Any setting can be overridden with an environment variable using the pattern
OPENSIM__Section__Key=value. For example,
OPENSIM__Region__RegionName=MyRegion overrides the region name without
editing the file.
If you are migrating from a C# OpenSimulator installation, welkin-migration
can import your existing .ini configuration files.
See the configuration reference for all available sections and keys.
Default assets
Welkin does not include the default avatar assets (body parts, clothing,
animations and sounds). They are Linden Lab viewer art under CC BY-SA 2.5, which
the OpenSimulator source tree labels in bin/data/LICENSE-README-IMPORTANT.txt,
and that license does not fit LGPL-3.0-or-later. Copy the bin/assets folder from
an OpenSimulator 0.9.3.0 install so that it sits beside welkin-robust, as
assets/AssetSets.xml, or set [AssetService] AssetLoaderArgs in robust.toml to
the path of your AssetSets.xml. On start, welkin-robust loads the sets into a
fresh robust.db (432 assets, 12.6 MB) and skips anything already stored, so
restarts are safe. Without the folder it logs a warning and avatars stay
untextured. AssetLoaderEnabled = false turns the loader off.
Run
Start the grid services first, then the region simulator:
# Terminal 1: grid services (public port 8002, private port 8003)
./target/release/welkin-robust --config robust.toml
# Terminal 2: region simulator (UDP 9000)
./target/release/welkin-region --config welkin.toml
The web portal and its first-run wizard do not work yet; the portal crate is a scaffold (see Grid Portal). Account creation and region placement through the portal are not available.
Connect a viewer
Point your viewer at the login URI http://127.0.0.1:8002/:
- Aurora Viewer: launch with
--loginuri http://127.0.0.1:8002/ - Firestorm: open Grid Manager, add a new grid with the login URI above, then select it and log in
Log in with an existing user account on the grid.
Standalone vs external grid
The steps above run a standalone grid: both binaries on one machine with a
local database. To connect a region to an existing grid instead, change
GridServerURI in welkin.toml to point at that grid's private service
endpoint. The region registers itself with the remote ROBUST and appears
on the grid map.
For OSGrid, set GridServerURI to OSGrid's grid service URL and follow
their registration process. See OSGrid compatibility
for details.