Ralith / Ralith/hecs

Queries that add/remove components

Open
#334 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Rust
Stars
1.4k
Forks
107
Avg merge
2h
Merged PRs (30d)
6

Description

Common patterns involve iterating over a query and adding, adding if absent, or removing a component from every entity. This presently requires a somewhat awkward and suboptimal dance where operations are buffered in a CommandBuffer or moral equivalent and executed in a separate pass after the query completes. We could extend the query machinery to support these patterns directly with query transformers that allow components to be directly written to or consumed from archetype storage, though considerable care will be required to soundly handle corner cases including incomplete iteration, leaked queries, and failure to insert all expected components.

Design notes:

  • Entities must be moved only after they are visited. Before would prevent dynamic addition/removal decisions, and during would invalidate live component references.
  • Moving entities between archetypes naively can cause them to be visited multiple times. Because entities are always inserted at the end of an archetype, this could be avoided by capturing a snapshot of the len of each archetype when the query begins, and halting iteration at that point.
  • Components cannot be moved while any borrows from the query are still live. Movement of entities between archetypes must therefore happen no sooner than the Drop impl of an object that outlives the query lifetime. This will require a guard object, and is therefore incompatible with the existing query_mut/query_one_mut API.
  • Two new Query methods:
    • One that traverses the archetype graph to reflect component insertion/removals. Compound queries execute this for each inner query in any order to arrive at the final archetype.
    • One that populates entries in the final archetype
  • Care must be taken to preserve safety in the presence of arbitrary drops, unwinds, and leaks of the query iterator and any query items.
    • A query that yields ownership of components must poison affected archetypes until cleanup completes
  • QueryMut and similar must carry borrows of the whole World so they can add new archetypes

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the query machinery and the Query and QueryMut APIs described in the issue; no specific source file or test is named. Completion requires safe direct component insertion and removal while preserving iteration, borrowing, unwind, and leak safety across the listed corner cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
game-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.