@aethervtt/shard-project 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-project
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/define.d.ts

@@ -0,0 +1,55 @@
+import { type DataType, type DataTypeOptions } from '@aethervtt/shard-assets';
+import { type ComponentDef, type ComponentOptions, type EventDef, type Fields, type ResourceDef, type ResourceOptions, type TagDef } from '@aethervtt/shard-core';
+import { type Generator, type GeneratorOptions, type OutputSpec } from '@aethervtt/shard-procgen';
+import { type MaterialType, type MaterialTypeOptions } from '@aethervtt/shard-render';
+import type { App, Plugin } from '@aethervtt/shard-runtime';
+import { type SettingsDef } from '@aethervtt/shard-save';
+export interface ProjectOptions {
+    /** Must match `shard.json`'s name. Becomes the namespace of every project type. */
+    name: string;
+    build?(app: App): void;
+    ready?(app: App): Promise<void> | void;
+}
+export interface ProjectDef extends Plugin {
+    readonly namespace: string;
+    /** Defines `<project>/<name>`. A name in another namespace throws `project/namespace`. */
+    component<const F extends Fields>(name: string, fields: F, options?: ComponentOptions): ComponentDef<F>;
+    tag(name: string, options?: {
+        description?: string;
+    }): TagDef;
+    resource<T>(name: string, options?: ResourceOptions<T>): ResourceDef<T>;
+    event<T = undefined>(name: string, options?: {
+        description?: string;
+    }): EventDef<T>;
+    /**
+     * Defines the project's settings, `<project>/Settings`: a resource persisted per player in
+     * `settings.json` (defaults from `settings/*.json`), loaded before Startup. Read it like any
+     * resource; `setSettings` changes it and applies at once.
+     */
+    settings<const F extends Fields>(fields: F, options?: Pick<ComponentOptions, 'description' | 'version' | 'migrate'> & {
+        name?: string;
+    }): SettingsDef<F>;
+    /**
+     * Defines the material type `<project>/<name>`: fields (numbers, colors, texture handles) and a
+     * shader in `shaders/` (`project::<file>`) that overrides hooks. Assets name it in `"type"`.
+     */
+    material<const F extends Fields>(name: string, options: MaterialTypeOptions<F>): MaterialType;
+    /**
+     * Defines the data asset type `<project>/<name>`: `*.<extension>.json` files under the asset
+     * roots are validated by `fields`, can `$extends` each other, and load into `store`. Components
+     * reference them with `t.handle('<project>/<name>')`.
+     */
+    dataAsset<const F extends Fields, const N extends string>(name: N, fields: F, options: DataTypeOptions): DataType<F, N extends `${string}/${string}` ? N : `${string}/${N}`>;
+    /**
+     * Defines the generator `<project>/<name>`: `(seed, params) → output` (a mesh, texture, data
+     * value, or entities), cached by the hash of its inputs and run on the worker pool. Place its
+     * output with a `generators/*.gen.json` file, a `procedural:<project>/<name>?…` ref, a
+     * `procgen/GeneratorInstance`, or `generate(world, gen, params, seed)`.
+     */
+    generator<const P extends Fields, const O extends OutputSpec>(name: string, options: GeneratorOptions<P, O>): Generator<P, O>;
+}
+/**
+ * The project plugin: the game's own code, exported as the default of `scripts/main.ts`. Project
+ * types are namespaced by the project name, so they never collide with engine types.
+ */
+export declare function defineProject(options: ProjectOptions): ProjectDef;

package/dist/define.js

@@ -0,0 +1,56 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineEvent,
+  defineResource,
+  defineTag,
+  ShardError
+} from "@aethervtt/shard-core";
+import {
+  defineGenerator
+} from "@aethervtt/shard-procgen";
+import {
+  defineMaterial
+} from "@aethervtt/shard-render";
+import { defineSettings } from "@aethervtt/shard-save";
+function defineProject(options) {
+  const ns = options.name;
+  const qualify = (name) => {
+    const slash = name.indexOf("/");
+    if (slash === -1) return `${ns}/${name}`;
+    if (name.slice(0, slash) !== ns) {
+      throw new ShardError(
+        "project/namespace",
+        `"${name}" is outside the project namespace "${ns}"`,
+        {
+          hint: `Project types are named "${ns}/<Name>"; pass just "<Name>".`
+        }
+      );
+    }
+    return name;
+  };
+  return {
+    name: `project:${ns}`,
+    namespace: ns,
+    dependencies: ["core/time"],
+    build: (app) => options.build?.(app),
+    ready: (app) => options.ready?.(app),
+    component: (name, fields, componentOptions) => defineComponent(qualify(name), fields, componentOptions),
+    tag: (name, tagOptions) => defineTag(qualify(name), tagOptions),
+    resource: (name, resourceOptions) => defineResource(qualify(name), resourceOptions),
+    event: (name, eventOptions) => defineEvent(qualify(name), eventOptions),
+    settings: (fields, settingsOptions = {}) => {
+      const { name = "Settings", ...rest } = settingsOptions;
+      return defineSettings(qualify(name), fields, {
+        description: `${ns} settings, persisted per player.`,
+        ...rest
+      });
+    },
+    material: (name, materialOptions) => defineMaterial(qualify(name), materialOptions),
+    dataAsset: (name, fields, dataOptions) => defineDataType(qualify(name), fields, dataOptions),
+    generator: (name, generatorOptions) => defineGenerator(qualify(name), generatorOptions)
+  };
+}
+export {
+  defineProject
+};

package/dist/docs.d.ts

@@ -0,0 +1,26 @@
+import { type DataType, type ImporterDef } from '@aethervtt/shard-assets';
+import { type ComponentDef } from '@aethervtt/shard-core';
+import { type Generator } from '@aethervtt/shard-procgen';
+import { type ManifestValue } from './manifest.js';
+export declare const GENERATED_START = "<!-- shard:generated -->";
+export declare const GENERATED_END = "<!-- /shard:generated -->";
+export interface ErrorCode {
+    code: string;
+    hint?: string;
+    /** Package or file it comes from. */
+    source: string;
+}
+/** A readable catalog of components: the same facts as the JSON Schemas, for agents to skim. */
+export declare function renderComponentCatalog(defs?: readonly ComponentDef[]): string;
+export declare function renderErrorCatalog(codes: readonly ErrorCode[]): string;
+/**
+ * Importers: which files they handle, what they produce, and their `.meta` settings. Then the
+ * project's own data types: fields, file extension, and schema.
+ */
+export declare function renderAssetCatalog(importers?: readonly ImporterDef[], dataTypes?: readonly DataType[]): string;
+/** Every generator: what it makes, its params with units and ranges, and an example file. */
+export declare function renderGeneratorCatalog(gens?: readonly Generator[]): string;
+/** Replaces the generated block in AGENTS.md, keeping everything outside the markers. */
+export declare function mergeAgentsMd(existing: string | undefined, manifest: ManifestValue): string;
+/** Every generated file except AGENTS.md (see `mergeAgentsMd`), by project-relative path. */
+export declare function generateDocs(manifest: ManifestValue, errors: readonly ErrorCode[]): Record<string, string>;