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

オープン
  • 何か問題がありますか？
#259 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
15/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
typescript
領域
compilers

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
TypeScript
スター
12
フォーク
8
平均マージ
11時間 2分
マージ済み PR（30日）
23

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

adobe/data のほかの issue

adobe/data の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。