bevy_semantics 0.2.0

Semantic identity, ontology, and query infrastructure for Bevy
Documentation

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:

  • Wolf
  • preys_on
  • Forest

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 Relation kind 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:

struct SemanticEdge {
    subject: Kind,
    relation: Kind,
    target: Kind,
    weight: Option<Weight>,
}
  • subject, relation, and target identify the edge
  • weight is optional
  • unweighted edges are the default
  • Weight is a signed i64 newtype

Storage Model

The crate splits mutation and read access:

  • SemanticRegistry is the mutable source of truth
  • SemanticSnapshot is the immutable read model
  • Semantics is 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 side
  • ResMut<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("preys_on")
    .register_kind("predated_by")
    .typed_kind_named::<Wolf>("Wolf")
    .add_edge(wolf, preys_on, rabbit)
    .add_edge_weighted(wolf, damage, rabbit, Weight::from(7))
    .expect("seed semantic schema");

SemanticEdit

Use this for fluent bulk authoring.

It supports:

  • register_kind
  • typed_kind
  • typed_kind_named
  • unregister_kind
  • unregister_namespace
  • add_edge
  • add_edge_weighted
  • remove_edge
  • expect(...)
  • 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 SemanticCommand values
  • 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_of
  • part_of inverse_of has_part
  • is_a negates not_a
  • not_a negates is_a
  • can_be negates cant_be
  • cant_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 -> Wolf
  • Creature -> Beast -> Rabbit
  • Item -> Resource -> Herb
  • Item -> Loot -> Pelt
  • Place -> Forest

Custom demo relations:

  • preys_on / predated_by
  • drops / dropped_by
  • grows_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 SemanticCommand values
  • 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

  • Kind and Weight are opaque newtypes, not type aliases.
  • Relations are unweighted by default. Use weighted edges only when the scalar matters.
  • Core kinds are protected. unregister_kind removes 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.