world-engine

module

v0.20.0 Latest Latest Go to latest Published: Oct 10, 2026 License: LGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/argus-labs/world-engine

Links

Open Source Insights

README ¶

The world’s first Gamechain SDK that utilizes Argus Labs’ novel sharded rollup architecture.

⚠️ Work in Progress

Hey there!

We're in the process of rewriting the World Engine from the ground up.

Stay tuned!

Development

Install proto, then run proto install from the repository root to install the Go and moon versions in .prototools. Keep proto's shims on your PATH so go and moon use those versions.

moon tasks                          # List project tasks
moon run world-engine:build          # Build Go packages
moon run world-engine:lint           # Lint (installs the pinned linter)
moon run world-engine:lint-fix       # Apply lint fixes
moon run world-engine:test           # Run all Go tests
moon run world-engine:test-ci        # Write coverage.out and junit.xml
TEST_SEED=123 moon run world-engine:test  # Replay a test seed

golangci-lint installs into the ignored bin/tools directory. gotestsum runs through go tool. Failing tests log a seed for reproduction. Moon task caching is disabled so randomized tests run each time. Go's own compilation and test caches remain enabled.

Generated clients have separate projects:

moon run proto-csharp:build or proto-csharp:pack builds or packages the C# client. Requires the .NET SDK. Debug variants use build-debug and pack-debug.
moon run proto-ts:build type-checks the TypeScript client. Requires Node/npm and a prior npm install in proto/gen/ts.

Moon replaces both Taskfiles. Task names use hyphens, for example test:ci becomes world-engine:test-ci. C# rebuild cleans before building, and update reports outdated dependencies without changing them. Formatting and analysis failures propagate to the caller.

CI runs the same Go tasks as local development. The Box2D workflow retains its separate architecture matrix and explicit determinism-* targets. Workflows select explicit targets instead of moon ci, keeping the expensive determinism checks in their dedicated matrix. Generated clients can be selected explicitly on runners with their SDKs installed. Cleanup and formatting never run automatically.

Directories ¶

Path	Synopsis
cardinal module
chain module
cli
cmd/world command
commands/debugger
commands/mcp
commands/root
commands/root/tui
commands/sdk Package sdk implements `world sdk` — generate a typed SDK (Go + C#) from a backend's Go command structs, via buf+protoc in Docker.	Package sdk implements `world sdk` — generate a typed SDK (Go + C#) from a backend's Go command structs, via buf+protoc in Docker.
internal/auth Package auth obtains an Argus JWT for calls to remote services, caching it between runs so a developer signs in roughly once a month.	Package auth obtains an Argus JWT for calls to remote services, caching it between runs so a developer signs in roughly once a month.
internal/debug Package debug drives a Cardinal shard's tick controls over DebugService.	Package debug drives a Cardinal shard's tick controls over DebugService.
internal/dependency
internal/errors
internal/logger
internal/logs
internal/printer
internal/sdkgen Package sdkgen reads command structs from a World Engine backend (Go source) and produces typed serde.	Package sdkgen reads command structs from a World Engine backend (Go source) and produces typed serde.
internal/store
internal/telemetry
internal/tui/component/logtail Package logtail displays streamed logs and handles tail-session input.	Package logtail displays streamed logs and handles tail-session input.
internal/tui/component/phasebox
internal/tui/component/spinner
internal/tui/component/table_page_select
internal/tui/component/table_select
internal/tui/component/table_view
internal/tui/component/textinput
internal/tui/kit/keys Package keys holds bindings and help rendering shared by TUI components.	Package keys holds bindings and help rendering shared by TUI components.
internal/tui/kit/program
internal/tui/kit/steps
internal/tui/style
pkg/cluster
pkg/dnslabel Package dnslabel normalizes arbitrary strings into DNS-label-safe path segments.	Package dnslabel normalizes arbitrary strings into DNS-label-safe path segments.
pkg/docker
pkg/docker/service
pkg/k8s/cardinal-operator Package cardinaloperator holds the logic and embedded manifests world-cli uses to run shards on a local k3d cluster through cardinal-operator.	Package cardinaloperator holds the logic and embedded manifests world-cli uses to run shards on a local k3d cluster through cardinal-operator.
pkg/modfile
pkg/toml
pkg/version
pkg/worldscaffold
proto/gen/go/cardinal/operator/v1
proto/gen/go/cardinal/operator/v1/operatorv1connect
e2e
tests module
magefiles module
pkg
assert
box2d Package box2d is a native Go port of Box2D v3.2.0, the 2D physics engine by Erin Catto (https://github.com/erincatto/box2d).	Package box2d is a native Go port of Box2D v3.2.0, the 2D physics engine by Erin Catto (https://github.com/erincatto/box2d).
cardinal Package cardinal runs a World Engine game shard.	Package cardinal runs a World Engine game shard.
cardinal/internal/command
cardinal/internal/ecs
cardinal/internal/event
cardinal/internal/introspect
cardinal/internal/schema
cardinal/snapshot
immutable Package immutable holds value types that keep their storage private, so nothing outside this package can reach into one.	Package immutable holds value types that keep their storage private, so nothing outside this package can reach into one.
micro
plugin/data Package data is a Cardinal plugin that loads JSON configuration into a world-owned catalog at world init.	Package data is a Cardinal plugin that loads JSON configuration into a world-owned catalog at world init.
plugin/data/component Package component holds the Cardinal components the data plugin owns.	Package component holds the Cardinal components the data plugin owns.
plugin/data/gen Code generated by world sdk generate.	Code generated by world sdk generate.
plugin/data/gen/pkg/plugin/data/component
plugin/data/system
plugin/lobby Package lobby provides a flexible lobby/party system for Cardinal worlds.	Package lobby provides a flexible lobby/party system for Cardinal worlds.
plugin/lobby/component
plugin/lobby/gen Code generated by world sdk generate.	Code generated by world sdk generate.
plugin/lobby/gen/pkg/plugin/lobby/component
plugin/lobby/gen/pkg/plugin/lobby/system
plugin/lobby/system
plugin/physics2d Package physics2d is a Box2D-backed 2D physics plugin for Cardinal (pure-Go Box2D port in pkg/box2d).	Package physics2d is a Box2D-backed 2D physics plugin for Cardinal (pure-Go Box2D port in pkg/box2d).
plugin/physics2d/component
plugin/physics2d/event
plugin/physics2d/gen Code generated by world sdk generate.	Code generated by world sdk generate.
plugin/physics2d/gen/pkg/plugin/physics2d/component
plugin/physics2d/gen/pkg/plugin/physics2d/event
plugin/physics2d/gen/pkg/plugin/physics2d/test/e2e/internal_/probe
plugin/physics2d/internal
plugin/physics2d/internal/system
plugin/physics2d/query Package query declares the request, result, and filter types for the physics2d query API (raycast, AABB overlap, circle sweep).	Package query declares the request, result, and filter types for the physics2d query API (raycast, AABB overlap, circle sweep).
plugin/physics2d/test/e2e/cmd/physics2d-e2e command Command game is the physics2d test game: a Cardinal world whose only job is to exercise the physics2d plugin and report anything that does not behave the way Box2D does.	Command game is the physics2d test game: a Cardinal world whose only job is to exercise the physics2d plugin and report anything that does not behave the way Box2D does.
plugin/physics2d/test/e2e/internal/harness
plugin/physics2d/test/e2e/internal/probe Package probe holds the ECS components this test game adds on top of the physics2d plugin's own Transform2D / Velocity2D / PhysicsBody2D.	Package probe holds the ECS components this test game adds on top of the physics2d plugin's own Transform2D / Velocity2D / PhysicsBody2D.
plugin/physics2d/test/e2e/internal/restore Package restore drives the crash-restore check: snapshot a running world, rebuild it in a fresh one, and compare.	Package restore drives the crash-restore check: snapshot a running world, rebuild it in a fresh one, and compare.
plugin/physics2d/test/e2e/internal/scenario Package scenario holds the individual physics2d test scenarios.	Package scenario holds the individual physics2d test scenarios.
telemetry
telemetry/posthog
telemetry/sentry
telemetry/trace Package trace is a light wrapper over the OpenTelemetry tracing API, modeled on Sourcegraph's internal/trace: one constructor bound to the global tracer provider and a Trace type that adds error helpers to the span.	Package trace is a light wrapper over the OpenTelemetry tracing API, modeled on Sourcegraph's internal/trace: one constructor bound to the global tracer provider and a Trace type that adds error helpers to the span.
template/bare-bone/shards/game command
template/basic/pkg/other_worlds
template/basic/shards/game command
template/basic/shards/game/component
template/basic/shards/game/event
template/basic/shards/game/gen Code generated by world sdk generate.	Code generated by world sdk generate.
template/basic/shards/game/gen/pkg/template/basic/shards/game/component
template/basic/shards/game/gen/pkg/template/basic/shards/game/event
template/basic/shards/game/gen/pkg/template/basic/shards/game/system
template/basic/shards/game/gen/pkg/template/basic/shards/game/system_event
template/basic/shards/game/system
template/basic/shards/game/system_event
template/multi-shard/pkg/other_world
template/multi-shard/shards/chat command
template/multi-shard/shards/chat/command
template/multi-shard/shards/chat/component
template/multi-shard/shards/chat/event
template/multi-shard/shards/chat/gen Code generated by world sdk generate.	Code generated by world sdk generate.
template/multi-shard/shards/chat/gen/pkg/template/multi-shard/shards/chat/command
template/multi-shard/shards/chat/gen/pkg/template/multi-shard/shards/chat/component
template/multi-shard/shards/chat/gen/pkg/template/multi-shard/shards/chat/event
template/multi-shard/shards/chat/system
template/multi-shard/shards/game command
template/multi-shard/shards/game/command
template/multi-shard/shards/game/component
template/multi-shard/shards/game/event
template/multi-shard/shards/game/gen Code generated by world sdk generate.	Code generated by world sdk generate.
template/multi-shard/shards/game/gen/pkg/template/multi-shard/shards/game/command
template/multi-shard/shards/game/gen/pkg/template/multi-shard/shards/game/component
template/multi-shard/shards/game/gen/pkg/template/multi-shard/shards/game/event
template/multi-shard/shards/game/system
testutils
proto
gen/go/worldengine/cardinal/v1
gen/go/worldengine/cardinal/v1/cardinalv1connect
gen/go/worldengine/isc/v1
gen/go/worldengine/micro/v1
sign module

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL