v0.6.1 - La Femme d'argent

Following up the relation rewrite, events have been normalized for relations so that they are more reliable.

• Any time a relation pair is added to an entity, it will emit an add event, ie entity.add(Likes(alice)), even if it is not first instance of that relation on the entity. Ie, the entity already has a like relation to another entity.
• Any time a relation pair is removed from an entity, it will emit a remove event, ie entity.remove(Likes(alice)), even if it is not the last relation pair of that type on the entity.
• A change event will only be emitted if the relation has data via the store prop and has been updated with entity.set(Likes(alice), { amount: 10 }).
• When a relation is exclusive and a replcement is set, the old pair will get a remove event and the new pair will get an add event.

In addition, callbacks have a different signature for relations and will return entity and target instead of just entity.

const Likes = relation()

const unsub = world.onAdd(Likes, (entity, target) => {
  console.log(`Entity ${entity} likes ${target}`)
})

This allowed for introducing a two new React hooks, useTarget and useTargets.

const ChildOf = relation()

function ParentDisplay({ entity }) {
  // Returns the first target of the ChildOf relation
  const parent = useTarget(entity, ChildOf)

  if (!parent) return <div>No parent</div>

  return <div>Parent: {parent.id()}</div>
}

const Contains = relation()

function InventoryDisplay({ entity }) {
  // Returns all targets of the Contains relation
  const items = useTargets(entity, Contains)

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id()}>Item {item.id()}</li>
      ))}
    </ul>
  )
}

Some refactoring has also been underway. In an effort to consolidate and standardize the internal concepts, a ref/instance pattern was implemented. In short, a pattern emerged in Koota where a global handler called a ref gets created, such as a trait, and then it gets instantiated per-world when registered with it. As far as user-facing code goes, the biggest change is that cacheQuery has been deprecated in favor of createQuery which now follows this pattern. A query ref is returned that defines the query and also acts as a cache key. In addition there are the following changes and deprecations to type definitions in order to standardize the naming:

• TraitData (now TraitInstance)
• ModifierData (now Modifier)
• Internal types like TraitInstance, QueryInstance will be removed

What's Changed

Features

• core: Improve relation events on a per-target basis by @krispya in #198
• react: Add useTarget and useTargets hooks by @krispya in #199

Fixes

• react: useTrait should return undefined when the target entity becomes undefined by @mdirolf in #189
• react: useTag and useHas return false for undefined entity by @krispya in #190
• core: Fix tag getter by @krispya in #197

Chores

• core: Refactor internals for explicit storage domain by @krispya in #193
• core: Refactor world to function by @krispya in #194
• ore: Refactor internals to follow ref/instance pattern by @krispya in #196

New Contributors

• @mdirolf made their first contribution in #189

Full Changelog: v0.6.0...v0.6.1