Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(core): lift TIJ patterns into core (atlas-profiles, candidate-profile, chroma-repair)
Matt Kissinger84e3591bb8fd
diff --git a/imposter/__tests__/atlas-profiles.test.ts b/imposter/__tests__/atlas-profiles.test.tsnew file mode 100644index 00000000..8aafaad8--- /dev/null+++ b/imposter/__tests__/atlas-profiles.test.ts@@ -0,0 +1,115 @@+import { describe, expect, test } from 'bun:test';++import {+ ATLAS_PROFILES,+ ATLAS_PROFILE_NAMES,+ isAtlasProfileName,+ validateAgainstAtlasProfile,+} from '../atlas-profiles';++describe('atlas-profiles catalog', () => {+ test('exports four named profiles', () => {+ const names: string[] = [...ATLAS_PROFILE_NAMES];+ expect(names.sort()).toEqual(+ ['canopy-balanced', 'canopy-hero', 'ground-compact', 'mid-balanced'],+ );+ });++ test('ground-compact does not require normal layer', () => {+ expect(ATLAS_PROFILES['ground-compact'].normalRequired).toBe(false);+ });++ test('canopy-* and mid-balanced require normal layer', () => {+ expect(ATLAS_PROFILES['mid-balanced'].normalRequired).toBe(true);+ expect(ATLAS_PROFILES['canopy-balanced'].normalRequired).toBe(true);+ expect(ATLAS_PROFILES['canopy-hero'].normalRequired).toBe(true);+ });++ test('hero allows the largest tiles', () => {+ expect(ATLAS_PROFILES['canopy-hero'].maxTileSize).toBe(1024);+ expect(ATLAS_PROFILES['ground-compact'].maxTileSize).toBe(256);+ });+});++describe('isAtlasProfileName', () => {+ test('accepts the four named profiles', () => {+ expect(isAtlasProfileName('ground-compact')).toBe(true);+ expect(isAtlasProfileName('mid-balanced')).toBe(true);+ expect(isAtlasProfileName('canopy-balanced')).toBe(true);+ expect(isAtlasProfileName('canopy-hero')).toBe(true);+ });++ test('rejects non-string and unknown values', () => {+ expect(isAtlasProfileName('made-up-profile')).toBe(false);+ expect(isAtlasProfileName(undefined)).toBe(false);+ expect(isAtlasProfileName(42)).toBe(false);+ expect(isAtlasProfileName(null)).toBe(false);+ });+});++describe('validateAgainstAtlasProfile', () => {+ test('clean ground-compact meta passes', () => {+ const result = validateAgainstAtlasProfile(+ { tileSize: 256, angles: 8 },+ 'ground-compact',+ );+ expect(result.ok).toBe(true);+ expect(result.violations).toEqual([]);+ expect(result.profile).toBe('ground-compact');+ });++ test('flags tileSize over the profile max', () => {+ const result = validateAgainstAtlasProfile(+ { tileSize: 1024, angles: 8 },+ 'ground-compact',+ );+ expect(result.ok).toBe(false);+ expect(result.violations.some((v) => v.field === 'tileSize')).toBe(true);+ });++ test('flags angles over the profile max', () => {+ const result = validateAgainstAtlasProfile(+ { tileSize: 256, angles: 32 },+ 'ground-compact',+ );+ expect(result.ok).toBe(false);+ expect(result.violations.some((v) => v.field === 'angles')).toBe(true);+ });++ test('flags missing normal aux layer when required', () => {+ const result = validateAgainstAtlasProfile(+ { tileSize: 512, angles: 16, auxLayers: [], normalSpace: 'capture-view' },+ 'mid-balanced',+ );+ expect(result.ok).toBe(false);+ expect(result.violations.some((v) => v.field === 'normal-aux-layer')).toBe(true);+ });++ test('flags wrong normalSpace when normal layer is required', () => {+ const result = validateAgainstAtlasProfile(+ { tileSize: 512, angles: 16, auxLayers: ['normal'], normalSpace: 'world' },+ 'canopy-balanced',+ );+ expect(result.ok).toBe(false);+ expect(result.violations.some((v) => v.field === 'normal-space')).toBe(true);+ });++ test('passes valid canopy-hero meta with normal layer + capture-view space', () => {+ const result = validateAgainstAtlasProfile(+ {+ tileSize: 1024,+ angles: 32,+ auxLayers: ['normal'],+ normalSpace: 'capture-view',+ },+ 'canopy-hero',+ );+ expect(result.ok).toBe(true);+ expect(result.limits.maxTileSize).toBe(1024);+ });++ test('skips numeric checks if fields are absent (read-only validator)', () => {+ const result = validateAgainstAtlasProfile({}, 'ground-compact');+ expect(result.ok).toBe(true);+ });+});diff --git a/imposter/atlas-profiles.ts b/imposter/atlas-profiles.tsnew file mode 100644index 00000000..766ba611--- /dev/null+++ b/imposter/atlas-profiles.ts@@ -0,0 +1,107 @@+/**+ * Atlas profile rules for static (lat-lon / hemi-y) imposter bakes.+ *+ * Profiles define the maximum tile size, angle count, and whether a normal+ * aux layer is required for a given imposter "tier" (ground cover vs canopy+ * etc). Originally lived inline in scripts/validate-tij-vegetation-package.ts;+ * lifted to core in W6 so non-TIJ consumers can reuse the same contract.+ *+ * Species-to-profile mapping stays in the consumer (e.g. TIJ vegetation+ * pipeline) — profiles describe the *bake contract*, not the catalog.+ */++export const ATLAS_PROFILES = {+ 'ground-compact': { maxTileSize: 256, maxAngles: 8, normalRequired: false },+ 'mid-balanced': { maxTileSize: 512, maxAngles: 16, normalRequired: true },+ 'canopy-balanced': { maxTileSize: 512, maxAngles: 32, normalRequired: true },+ 'canopy-hero': { maxTileSize: 1024, maxAngles: 32, normalRequired: true },+} as const;++export type AtlasProfileName = keyof typeof ATLAS_PROFILES;+export type AtlasProfileLimits = (typeof ATLAS_PROFILES)[AtlasProfileName];++export const ATLAS_PROFILE_NAMES = Object.keys(ATLAS_PROFILES) as AtlasProfileName[];++export function isAtlasProfileName(value: unknown): value is AtlasProfileName {+ return typeof value === 'string' && value in ATLAS_PROFILES;+}++/**+ * Subset of static-imposter sidecar fields the profile cares about.+ * Accepts unknown so callers can pass JSON-parsed metadata directly.+ */+export interface AtlasProfileMetaInput {+ tileSize?: unknown;+ angles?: unknown;+ auxLayers?: unknown;+ normalSpace?: unknown;+}++export type AtlasProfileViolationField =+ | 'tileSize'+ | 'angles'+ | 'normal-aux-layer'+ | 'normal-space';++export interface AtlasProfileViolation {+ field: AtlasProfileViolationField;+ message: string;+}++export interface AtlasProfileValidationResult {+ ok: boolean;+ profile: AtlasProfileName;+ limits: AtlasProfileLimits;+ violations: AtlasProfileViolation[];+}++/**+ * Validates an imposter sidecar (or atlas metadata) against the named profile.+ * Returns { ok, violations[] } so callers can render their own error format.+ *+ * Read-only. Does not throw — invalid profile names produce a violation list+ * with `ok: false`. Pass a real `AtlasProfileName` (typed) and you'll get a+ * clean limits echo on success.+ */+export function validateAgainstAtlasProfile(+ meta: AtlasProfileMetaInput,+ profile: AtlasProfileName,+): AtlasProfileValidationResult {+ const limits = ATLAS_PROFILES[profile];+ const violations: AtlasProfileViolation[] = [];++ if (typeof meta.tileSize === 'number' && meta.tileSize > limits.maxTileSize) {+ violations.push({+ field: 'tileSize',+ message: `tileSize=${meta.tileSize} exceeds profile ${profile} max ${limits.maxTileSize}`,+ });+ }+ if (typeof meta.angles === 'number' && meta.angles > limits.maxAngles) {+ violations.push({+ field: 'angles',+ message: `angles=${meta.angles} exceeds profile ${profile} max ${limits.maxAngles}`,+ });+ }+ if (limits.normalRequired) {+ const aux = Array.isArray(meta.auxLayers) ? (meta.auxLayers as unknown[]) : [];+ if (!aux.includes('normal')) {+ violations.push({+ field: 'normal-aux-layer',+ message: `profile ${profile} requires the 'normal' aux layer`,+ });+ }+ if (meta.normalSpace !== 'capture-view') {+ violations.push({+ field: 'normal-space',+ message: `profile ${profile} requires normalSpace='capture-view' (got ${String(meta.normalSpace)})`,+ });+ }+ }++ return {+ ok: violations.length === 0,+ profile,+ limits,+ violations,+ };+}diff --git a/imposter/index.ts b/imposter/index.tsindex 71e2d5db..b52bd82f 100644--- a/imposter/index.ts+++ b/imposter/index.ts@@ -12,6 +12,21 @@export { bakeImposter, openImposterSession } from './bake';export type { BakeImposterOptions, BakeImposterResult, ImposterSession } from './bake';+export {+ ATLAS_PROFILES,+ ATLAS_PROFILE_NAMES,+ isAtlasProfileName,+ validateAgainstAtlasProfile,+} from './atlas-profiles';+export type {+ AtlasProfileLimits,+ AtlasProfileMetaInput,+ AtlasProfileName,+ AtlasProfileValidationResult,+ AtlasProfileViolation,+ AtlasProfileViolationField,+} from './atlas-profiles';+export {IMPOSTER_SCHEMA_VERSION,ImposterMetaSchema,diff --git a/index.ts b/index.tsindex 5f8e6fba..fadab75a 100644--- a/index.ts+++ b/index.ts@@ -212,6 +212,12 @@ export type {AnimatedTileCamera,BakeAnimatedImposterOptions,BakeAnimatedImposterResult,+ AtlasProfileLimits,+ AtlasProfileMetaInput,+ AtlasProfileName,+ AtlasProfileValidationResult,+ AtlasProfileViolation,+ AtlasProfileViolationField,NpcCharacterPackFactionMetrics,NpcCharacterPackIssue,NpcCharacterPackManifest,@@ -231,9 +237,13 @@ export {AnimatedImposterTextureLayoutSchema,AnimatedImposterTextureModeSchema,AnimatedImposterWarningSchema,+ ATLAS_PROFILES,+ ATLAS_PROFILE_NAMES,ImposterMetaSchema,IMPOSTER_SCHEMA_VERSION,estimateAnimatedImposterStorage,+ isAtlasProfileName,+ validateAgainstAtlasProfile,validateAnimatedImposterPreBake,bakeAnimatedImposter,enumerateOctahedralGrid,