bevy_semantics
bevy_semantics is a high-level semantic layer for Bevy and Rust projects.
It maps abstract concepts to stable kinds and records how those concepts relate.
It is not the definition of a thing, and it is not a runtime instance of a thing.
An ontology graph is the directed graph that stores that meaning:
- kinds are the nodes
- relations are kinds used as edge labels
- edges connect a subject kind, relation kind, and target kind
Use this crate when you want to answer questions like:
- what is this concept?
- what does it inherit from?
- what does it prey on?
- what does it drop?
- where does it grow?
Bevy Compatibility
| bevy_semantics | Bevy |
|---|---|
0.2.x |
0.19.x |
0.1.x |
0.18.x |
What This Crate Gives You
- stable semantic identities
- optional typed kinds
- a read-optimized ontology graph
- immutable snapshots for concurrent reads
- query compilation and caching
- built-in Bevy integration in the default build
Core Ideas
Kind
A Kind is a stable semantic identifier for a concept.
- it is opaque, not a string
- it is derived from a canonical name
- it is cheap to copy and safe to store in game data
- it names a concept, not an entity instance
Examples:
Wolfpreys_onForest
Relation
A relation is just a kind used in the relation slot of an edge.
- relations are not a separate storage type
- relation kinds are normal kinds
- the core
Relationkind marks kinds that are intended for use as edge labels
In other words, preys_on is both a kind and a relation label.
Edge
An edge is a semantic triple, with optional scalar metadata:
subject,relation, andtargetidentify the edgeweightis optional- unweighted edges are the default
Weightis a signedi64newtype
Storage Model
The crate splits mutation and read access:
SemanticRegistryis the mutable source of truthSemanticSnapshotis the immutable read modelSemanticsis the Bevy-facing resource that wraps both
The snapshot is built from the registry and uses dense internal indexing for reads. Public code never sees the dense index type.
API Overview
SemanticRegistry
Use this when authoring outside Bevy or in setup code.
Main methods:
register_kind(name)typed_kind::<T>()typed_kind_named::<T>(name)unregister_kind(kind)unregister_namespace(namespace)add_edge(subject, relation, target)add_edge_weighted(subject, relation, target, weight)remove_edge(subject, relation, target)batch()apply_commands(commands)core()kind(name)kind_of::<T>()name(kind)type_id(kind)snapshot()snapshot_cached()
batch() is for bulk authoring when you want to stage many writes and rebuild once at the end.
Semantics
Use this as Res<Semantics> or ResMut<Semantics> in Bevy.
Res<Semantics>is the read sideResMut<Semantics>is the write side- direct reads live here:
kind,kind_of,name,core - graph reads live here too:
is_a,targets,subjects,neighbors,reachable,can_reach,has_edge - direct writes live here:
register_kind,typed_kind,typed_kind_named,unregister_kind,unregister_namespace,add_edge,add_edge_weighted,remove_edge snapshot()returns the cached immutable read model for background work
Example shape:
semantics
.edit
.register_kind
.register_kind
.
.add_edge
.add_edge_weighted
.expect;
SemanticEdit
Use this for fluent bulk authoring.
It supports:
register_kindtyped_kindtyped_kind_namedunregister_kindunregister_namespaceadd_edgeadd_edge_weightedremove_edgeexpect(...)finish()
SemanticSnapshot
Use this for stable read-only work.
- it is immutable
- it can be cloned into background tasks
- it is the right surface for compiled queries
- direct reads do not need a snapshot
- background tasks do
Call semantics.snapshot() when you need a cloned read model.
SemanticPlaybackQueue
Use this when a background task produces semantic commands that should be replayed later on the main thread.
- a task reads a snapshot
- the task derives
SemanticCommandvalues - a main-thread system enqueues them
- the plugin replays them later
See examples/task_playback.rs for the full flow.
CommandsExt
Use this when you want to stage semantic edits from ordinary Bevy systems.
- it queues semantic commands through Bevy
Commands - the plugin drains and applies them later
- it is the easiest way to keep semantic authoring inside a Bevy schedule
Core
The crate seeds a small set of core kinds automatically. User code does not need to call an "ensure core" function.
The crate reserves the Core namespace for itself, but the seeded core kinds use plain names:
| Core kind | Use case |
|---|---|
Relation |
Marks relation kinds as part of the schema |
Namespace |
Reserved grouping kind for names and ownership |
is_a |
Taxonomy, inheritance, and required-component style hierarchies |
not_a |
Explicit exclusion or disjoint categories |
can_be |
Positive capability, affordance, or allowed classification |
cant_be |
Negative capability or disallowed classification |
has_part |
Composition from whole to part |
part_of |
Inverse composition from part to whole |
inverse_of |
Declare that two relations are inverses |
negates |
Declare logical opposites such as is_a vs not_a |
Core facts are seeded automatically:
- every relation kind
is_a Relation has_part inverse_of part_ofpart_of inverse_of has_partis_a negates not_anot_a negates is_acan_be negates cant_becant_be negates can_be
The Core namespace is reserved and cannot be removed, in any case variant.
Example World
The runnable examples use a small game-world-like ecosystem:
Creature -> Beast -> Canine -> WolfCreature -> Beast -> RabbitItem -> Resource -> HerbItem -> Loot -> PeltPlace -> Forest
Custom demo relations:
preys_on/predated_bydrops/dropped_bygrows_in
These custom relations are not core kinds.
Register them like any other kind, optionally classify them under Relation, and couple the paired relations with inverse_of.
If you want a full end-to-end example, see examples/basic.rs.
Background Tasks
SemanticSnapshot is designed to be cloned into background work.
The usual flow is:
- read a snapshot on a task
- derive a batch of
SemanticCommandvalues - enqueue them in
SemanticPlaybackQueue - replay them later on the main thread
That keeps background work deterministic and keeps the mutable registry on the main thread.
If you want a runnable example, see examples/task_playback.rs.
When A Relation Should Be An Entity
Use an entity for a relation when:
- the relation has its own component data
- the relation needs spawn/despawn lifecycle
- the relation must be queried like any other ECS object
In that case, keep the semantic relation kind as the stable label and let the entity carry the runtime data.
Benchmarks
Hardware and Tooling
- CPU: 13th Gen Intel Core i7-13700K
- cores: 16 physical, 24 logical
- memory: 32.0 GiB
- OS: Windows 11 Pro 64-bit, build 26200
- Rust:
rustc 1.91.1 (ed61e7d7e 2025-11-07) - target:
x86_64-pc-windows-msvc
Latest Criterion Results
Measured with cargo bench -p bevy_semantics --bench semantics_bench on the machine above after the API cleanup pass.
| Benchmark | Time |
|---|---|
semantics_snapshot_build_4k |
1.0560 ms - 1.0873 ms |
semantics_snapshot_cached_4k |
16.301 ns - 16.567 ns |
semantics_bulk_authoring_4k |
2.0926 ms - 2.1538 ms |
semantics_lookup_kind_by_name |
6.1803 ns - 6.4976 ns |
semantics_is_a_direct |
34.189 ns - 34.429 ns |
semantics_edge_query_dynamic |
47.730 ns - 48.824 ns |
semantics_edge_query_compiled |
34.345 ns - 35.166 ns |
semantics_traversal_dynamic |
52.202 ns - 54.122 ns |
semantics_traversal_compiled |
37.500 ns - 37.934 ns |
semantics_task_command_derivation_4k |
283.97 ns - 287.82 ns |
semantics_task_command_playback_4k |
37.739 us - 40.944 us |
Notes
KindandWeightare opaque newtypes, not type aliases.- Relations are unweighted by default. Use weighted edges only when the scalar matters.
- Core kinds are protected.
unregister_kindremoves user kinds, their incident edges, and any typed binding, but core kinds cannot be removed. - The crate favors deterministic results and cached reads over write-side sophistication.