ecs: let kernels issue commands through helpers (component lists, symbol-keyed values, void helpers)

Ouverte
  • Quelque chose ne va pas ?
#259 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
15/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
typescript
Domaine
compilers

Piste de recherche

The three failures come from the kernel subset checks: list resolution for commands.add (the lists.ts module that tracks definitions by file and name), the return <value> requirement for helpers, and the object-literal check on command values. Read subset.md first, then the compiler code behind those three error messages. Done means each repro in the issue builds with kernel: true and produces the same inlined output as the existing numeric and tuple cases.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

Summary

A kernel (kernel: true) can't issue a command through a helper unless the helper is written around several compiler limits. Every key is a module-scope Symbol() constant, so in principle the compiler can resolve all of it statically. This asks for the compiler to follow keys through helpers. It is an optimization of the compiler only; no public API changes.

Seen on @adobe/ecs 0.3.0 with Compiler.plugin().

Why it matters: the guidance is that a system that can be a kernel should be one (kernel: true fails the build when its body stops qualifying). Helpers that build "this entity gets these components with these values" are a natural thing to share between systems, and today they push those systems out of the kernel subset.

Minimal repro

keys.ts

export const tag = Symbol();
export const size = Symbol();
export const color = Symbol();
declare module '@adobe/ecs' {
    interface Components {
        [tag]: { type: boolean; default: false };
        [size]: { type: number; default: 1 };
        [color]: { type: number; default: 0 };
    }
}

main.ts

import { System } from '@adobe/ecs';
import { color, size } from './keys.js';
import { dress } from './dress.js';

export const viaHelper = System.create({ kernel: true, components: { with: [size, color] } }, (row, { commands }) => {
    dress(commands, row.entity, row[color]);
});

dress.ts (this is the form that builds, and only because main.ts also imports tag, see 1)

import type { System } from '@adobe/ecs';
import { color, size, tag } from './keys.js';

export const dress = (commands: System.Commands, entity: Parameters<System.Commands['despawn']>[0], c: number): number => {
    commands.add(entity, [size, color, tag], { [size]: 2, [color]: c, [tag]: true });
    return 0;
};

What fails, and what it could do instead

  1. The component list is resolved in the kernel's module, not the helper's.

    • With main.ts as above (it doesn't import tag): commands.add: lists name keys by identifiers bound at module scope. The helper's own list is read in the system module's scope, so a key the system module doesn't import fails, even though the helper imports it and the key is a plain top-level Symbol().
    • Naming the list as a constant in the helper's module (const look = [size, color, tag] as const; then commands.add(entity, look, ...)) fails with commands.add: look isn't bound at module scope. subset.md says a list may be "a constant ... in the kernel's module or imported, also through re-exports and namespaces", so I expected this to work.
    • Wanted: resolve a helper's list in the helper's module, then map each key to the definition (the build already tracks definitions by file and name for imported lists, see lists.ts).

  2. A helper whose only job is to issue commands must still return <value>. Without the return 0; above: dress must end with return <value>. Wanted: a helper with no result is fine (void).

  3. Command values must be written in place as an object literal.

    • commands.add(entity, [size, color, tag], values(c)), where values returns ({ [size]: 2, [color]: c, [tag]: true }) as const, fails with command values must be an object literal like { [position]: value }.
    • A local does too: const values = { [size]: 2, [color]: c, [tag]: true }; fails with struct literals use plain field names.
    • Wanted: allow computed keys that are identifiers of top-level Symbol() constants in a struct literal, track them through locals and helper returns, and match them to the command's list. That is the same resolution as 1 (a key identifier maps to a definition), so a command's values can be assembled by a helper and shared.

Notes

  • Everything in 1 to 3 inlines at build time already for numbers, tuples and structs with plain field names, so this extends the same inlining to symbol-keyed structs and component lists.
  • With these, helpers like "make this entity a thing with this look" could be shared by several kernel systems instead of copied into each.
Langage dominant
TypeScript
Étoiles
12
Forks
8
Merge moyen
10 h 25 min
PR mergées (30 j)
26

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de adobe/data

Toutes les issues de adobe/data

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.