@ecsframework/core 0.0.1

package/out/framework/flamecs/registry.d.ts

@@ -0,0 +1,315 @@
+import type { Modding } from "@flamework/core";
+import * as ecs from "@rbxts/jecs";
+import type { Signal } from "./signal";
+export interface Wrap<T> {
+    readonly _flamecs_type: T;
+}
+export interface Tag extends Wrap<undefined> {
+}
+export interface ChildOf extends Tag {
+}
+export interface Wildcard extends Tag {
+}
+export interface Name extends Wrap<string> {
+}
+export type Id<T = unknown> = ecs.Id<T>;
+export type Entity<T = unknown> = ecs.Entity<T>;
+export type Pair<P = undefined, O = undefined> = ecs.Pair<P, O>;
+export type ExtractPredicate<T> = T extends Pair<infer P, unknown> ? P : T;
+export type Unwrap<T> = T extends Wrap<infer Inner> ? Inner : T;
+export type ResolveValue<T> = Unwrap<ExtractPredicate<T>>;
+export type ResolveValues<T> = {
+    [K in keyof T]: ResolveValue<T[K]>;
+};
+export type ComponentKey<T> = Modding.Generic<T, "id">;
+export type PairKey<P, O> = Modding.Many<{
+    obj: ComponentKey<O extends defined ? O : Wildcard>;
+    pred: ComponentKey<P extends defined ? P : Wildcard>;
+}>;
+export type ResolveKey<T> = T extends Pair<infer P, infer O> ? PairKey<P, O> : ComponentKey<T>;
+export type ResolveKeys<T> = Modding.Many<{
+    [K in keyof T]: ResolveKey<T[K]>;
+}>;
+type TrailingUndefined<T extends Array<unknown>> = T extends [...infer Rest, undefined] ? [...TrailingUndefined<Rest>, undefined?] : T;
+export declare const scheduleComponent: Set<ecs.Entity<unknown>>;
+export declare const worldSignals: Map<ecs.World, {
+    added: Map<Entity, Signal<[Entity, unknown]>>;
+    changed: Map<Entity, Signal<[Entity, unknown]>>;
+    removed: Map<Entity, Signal<[Entity]>>;
+}>;
+/**
+ * Returns a signal that fires when a component is added to an entity.
+ *
+ * @template T - The type of the component.
+ * @param key - Flamework autogenerated key for the component.
+ * @returns A signal that fires when the component is added to any entity.
+ * @metadata macro
+ */
+export declare function added<T>(registery: ecs.World, key?: ComponentKey<T>): Signal<[Entity<T>, T]>;
+/**
+ * Returns a signal that fires when a component is removed from an entity.
+ *
+ * @template T - The type of the component.
+ * @param key - Flamework autogenerated key for the component.
+ * @returns A signal that fires when the component is removed from any entity.
+ * @metadata macro
+ */
+export declare function removed<T>(registery: ecs.World, key?: ComponentKey<T>): Signal<[Entity<T>]>;
+/**
+ * Returns a signal that fires when a component's value changes on an entity.
+ *
+ * @template T - The type of the component.
+ * @param key - Flamework autogenerated key for the component.
+ * @returns A signal that fires when the component's value changes on any
+ *   entity.
+ * @metadata macro
+ */
+export declare function changed<T>(registery: ecs.World, key?: ComponentKey<T>): Signal<[Entity<T>, T]>;
+export declare function hookListeners(registry: ecs.World, id: Entity): void;
+/**
+ * Registers an existing entity to the component registry.
+ *
+ * @template T - The type of the component.
+ * @param runtimeId - The runtime entity to be registered.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function reserve<T>(registry: ecs.World | undefined, runtimeId: Entity<Unwrap<T>>, key?: ComponentKey<T>): void;
+/**
+ * Defines a component that can be added to an entity. Components can either tag
+ * an entity (e.g., "this entity is an NPC"), store data for an entity (e.g.,
+ * "this entity is located at Vector3.new(10, 20, 30)"), or represent
+ * relationships between entities <Pair<P, O>> (e.g., "bob Likes alice") that
+ * may also store additional data (e.g., "bob Eats 10 apples").
+ *
+ * @template T - The type of the component.
+ * @param key - Flamework autogenerated key.
+ * @returns The component entity ID.
+ * @metadata macro
+ */
+export declare function component<T>(registry?: ecs.World, key?: ComponentKey<T>): Entity<Unwrap<T>>;
+/**
+ * Retrieves the ID of a component or a pair relationship.
+ *
+ * @template T - The type of the component.
+ * @param key - Flamework autogenerated key or pair key.
+ * @returns The component or pair ID.
+ * @metadata macro.
+ */
+export declare function getId<T>(registry?: ecs.World, key?: ResolveKey<T>): Id<ResolveValue<T>>;
+export declare function getKey<T>(runtimeId: Entity): T | undefined;
+/**
+ * Creates a new empty entity.
+ *
+ * @returns The created entity.
+ * @metadata macro
+ */
+export declare function spawn(registry: ecs.World): ecs.Tag;
+/**
+ * Creates a new entity with the specified tag components.
+ *
+ * @template T - The type of the components.
+ * @param keys - Flamework autogenerated keys.
+ * @returns The created entity.
+ * @metadata macro
+ */
+export declare function spawn<T extends Array<Tag>>(registry: ecs.World, keys?: ResolveKeys<T>): ecs.Tag;
+/**
+ * Creates a new entity with the specified components and their values.
+ *
+ * @template T - The type of the components.
+ * @param values - The values to set for the components.
+ * @param keys - Flamework autogenerated keys.
+ * @returns The created entity.
+ * @metadata macro
+ */
+export declare function spawn<T extends Array<unknown>>(registry: ecs.World, values: TrailingUndefined<ResolveValues<T>>, keys?: ResolveKeys<T>): ecs.Tag;
+/**
+ * Deletes the specified entity and all associated components.
+ *
+ * @param entity - The entity to delete.
+ */
+export declare function despawn(registry: ecs.World, entity: Entity): void;
+/**
+ * Adds or updates multiple components for the specified entity.
+ *
+ * @template T - The type of the components.
+ * @param entity - The entity to modify.
+ * @param keys - Flamework autogenerated keys.
+ * @metadata macro
+ */
+export declare function insert<T extends Array<Tag>>(registry: ecs.World, entity: Entity, keys?: ResolveKeys<T>): void;
+/**
+ * Adds or updates multiple components for the specified entity.
+ *
+ * @template T - The type of the components.
+ * @param entity - The entity to modify.
+ * @param values - The values to set for the components.
+ * @param keys - Flamework autogenerated keys.
+ * @metadata macro
+ */
+export declare function insert<T extends Array<unknown>>(registry: ecs.World, entity: Entity, values: TrailingUndefined<ResolveValues<T>>, keys?: ResolveKeys<T>): void;
+/**
+ * Adds a pair relationship with a specific target entity.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity to which the pair relationship is added.
+ * @param object - The target entity of the relationship (object of the pair).
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function add<T extends Pair<Tag>>(registry: ecs.World, entity: Entity, object: Entity, key?: ComponentKey<ExtractPredicate<T>>): void;
+/**
+ * Adds a fully defined pair to an entity. This is used when both the predicate
+ * and object of the pair are known at compile-time.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity to which the pair component is added.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function add<T extends Pair<Tag, defined>>(registry: ecs.World, entity: Entity, key?: ResolveKey<T>): void;
+/**
+ * Adds a component to an entity.
+ *
+ * @template T - The type of the component.
+ * @param entity - The entity to which the component is added.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function add<T extends Tag>(registry: ecs.World, entity: Entity, key?: ComponentKey<T>): void;
+/**
+ * Removes a pair relationship with a specific target entity.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity from which the pair relationship is removed.
+ * @param object - The target entity of the relationship (object of the pair).
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function remove<T extends Pair<defined>>(registry: ecs.World, entity: Entity, object: Entity, key?: ComponentKey<ExtractPredicate<T>>): void;
+/**
+ * Removes a fully defined pair from an entity. This is used when both the
+ * predicate and object of the pair are known at compile-time.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity from which the pair component is removed.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function remove<T extends Pair<defined, defined>>(registry: ecs.World, entity: Entity, key?: ResolveKey<T>): void;
+/**
+ * Removes a component from an entity.
+ *
+ * @template T - The type of the component.
+ * @param entity - The entity from which the component is removed.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function remove<T>(registry: ecs.World, entity: Entity, key?: ComponentKey<T>): void;
+/**
+ * Sets a value for a pair with a specific runtime target entity.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity to which the pair relationship is added.
+ * @param object - The target entity of the relationship (object of the pair).
+ * @param value - The value associated with the pair relationship.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function set<T extends Pair<defined>>(registry: ecs.World, entity: Entity, object: Entity, value: ResolveValue<T>, key?: ComponentKey<ExtractPredicate<T>>): void;
+/**
+ * Sets a value for a fully defined pair on an entity. This is used when both
+ * the predicate and object of the pair are known at compile-time.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity to which the pair component is added.
+ * @param value - The value associated with the pair component.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function set<T extends Pair<defined, defined>>(registry: ecs.World, entity: Entity, value: ResolveValue<T>, key?: ResolveKey<T>): void;
+/**
+ * Sets a value for a component on an entity.
+ *
+ * @template T - The type of the component.
+ * @param entity - The entity to which the component is added or updated.
+ * @param value - The value associated with the component.
+ * @param key - Flamework autogenerated key.
+ * @metadata macro
+ */
+export declare function set<T>(registry: ecs.World, entity: Entity, value: Unwrap<T>, key?: ComponentKey<T>): void;
+/**
+ * Retrieves the value of a pair relationship for a specific entity and target.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity from which to retrieve the pair relationship.
+ * @param object - The target entity of the relationship (object of the pair).
+ * @param key - Flamework autogenerated key.
+ * @returns The value associated with the pair relationship.
+ * @metadata macro
+ */
+export declare function get<T extends Pair<defined>>(registry: ecs.World, entity: Entity, object: Entity, key?: ComponentKey<ExtractPredicate<T>>): ResolveValue<T> | undefined;
+/**
+ * Retrieves the value of a component or pair for a specific entity.
+ *
+ * @template T - The type of the component or pair.
+ * @param entity - The entity from which to retrieve the component or pair.
+ * @param key - Flamework autogenerated key.
+ * @returns The value associated with the component or pair.
+ * @metadata macro
+ */
+export declare function get<T>(registry: ecs.World, entity: Entity, key?: ResolveKey<T>): ResolveValue<T> | undefined;
+/**
+ * Checks if a pair relationship exists for a specific entity and target.
+ *
+ * @template T - The type of the pair.
+ * @param entity - The entity to check for the pair relationship.
+ * @param object - The target entity of the relationship (object of the pair).
+ * @param key - Flamework autogenerated key.
+ * @returns True if the pair relationship exists, false otherwise.
+ * @metadata macro
+ */
+export declare function has<T extends Pair<defined>>(registry: ecs.World, entity: Entity, object: Entity, key?: ComponentKey<ExtractPredicate<T>>): boolean;
+/**
+ * Checks if a component or pair exists for a specific entity.
+ *
+ * @template T - The type of the component or pair.
+ * @param entity - The entity to check for the component or pair.
+ * @param key - Flamework autogenerated key.
+ * @returns True if the component or pair exists, false otherwise.
+ * @metadata macro
+ */
+export declare function has<T>(registry: ecs.World, entity: Entity, key?: ResolveKey<T>): boolean;
+/**
+ * Retrieves the target entity of a relationship involving the specified entity
+ * and component.
+ *
+ * @template T - The type of the component.
+ * @param entity - The entity to get the target for.
+ * @param key - Flamework autogenerated key.
+ * @returns The target entity if a relationship exists, or undefined otherwise.
+ * @metadata macro
+ */
+export declare function target<T>(registry: ecs.World, entity: Entity, key?: ComponentKey<T>): Entity | undefined;
+/**
+ * Retrieves the parent entity (target of the ChildOf relationship) for the
+ * given entity.
+ *
+ * @param entity - The entity for which to get the parent.
+ * @returns The parent entity, or undefined if no parent exists.
+ */
+export declare function parent(registry: ecs.World, entity: Entity): Entity | undefined;
+/**
+ * Creates a pair relationship between a component and an entity.
+ *
+ * @template P - The type of the predicate component.
+ * @template O - The type of the object component.
+ * @param object - The object entity.
+ * @param predicate - The predicate component key.
+ * @returns The pair ID.
+ * @metadata macro
+ */
+export declare function pair<P>(registry: ecs.World, object: Entity, predicate?: ComponentKey<P>): Pair<Unwrap<P>, unknown>;
+export declare function initWorld(registry: ecs.World): void;
+export {};