@directivegames/genesys.js 3.1.24

package/docs/deprecated/8-guide-user-interface-2.md

@@ -0,0 +1,600 @@
+# UI System Development Rules
+
+Use these rules when generating UI-related code for the game engine.
+
+## Core Principles
+
+### File Organization
+- HTML templates go in `/assets/ui/templates/`
+- CSS styles go in `/assets/ui/styles/`
+- TypeScript component classes go in `src/ui/components/`
+- Always use complete file paths with extensions when loading assets
+- Use descriptive names that match the UI component purpose
+- Export components from `src/ui/index.ts` for easy importing
+
+### Template System
+- Use `{{variable}}` syntax for data interpolation in HTML templates
+- Keep templates semantic and well-structured
+- Use CSS classes for styling, not inline styles in templates
+- Include comments to describe UI sections
+
+### HTML & CSS
+- Follow common best-practices for all HTML and CSS files generated
+- **Do NOT include positioning classes** in CSS (no .top-left, .bottom-right, etc.)
+- Keep CSS focused on visual styling only
+- Use `position: absolute` as base positioning in container classes
+
+### Typescript UI component code
+- Don't couple it with gameplay code
+- Expect data to come in from the gameplay code to update the component
+- Ensure there are public functions or delegates/events for the gameplay code to listen/modify the UI
+
+### Asset Loading Pattern
+```typescript
+// Always load both template and styles together
+const { template, styles } = await ENGINE.UIAssetLoader.loadUIAsset(
+  '@engine/assets/ui/templates/component-name.html',
+  '@engine/assets/ui/styles/component-name.css'
+);
+
+// Create layout with initial data
+const layout = ui.createLayout('component-id', {
+  template,
+  styles,
+  data: { /* initial values */ }
+});
+```
+
+## Component Architecture
+
+### Use BaseUIComponent Pattern
+All UI components should extend `BaseUIComponent` for consistency. **Component IDs are now automatically generated** from the class name:
+
+```typescript
+import { BaseUIComponent } from './BaseUIComponent.js';
+import type { BaseUIComponentOptions } from './BaseUIComponent.js';
+import type * as ENGINE from '../../index.js';
+
+export interface ComponentOptions extends BaseUIComponentOptions {
+  // Component-specific options
+  customProperty?: string;
+}
+
+export class ComponentName extends BaseUIComponent<ComponentOptions> {
+  protected getAssetPaths() {
+    return {
+      templatePath: '@engine/assets/ui/templates/component-name.html',
+      stylesPath: '@engine/assets/ui/styles/component-name.css'
+    };
+  }
+
+  protected getDefaultOptions(): Required<ComponentOptions> {
+    return {
+      visible: true,
+      customClasses: [],
+      customStyles: {},
+      customProperty: 'default'
+    };
+  }
+
+  protected getInitialData() {
+    return {
+      // Template data
+    };
+  }
+
+  protected cacheElements(): void {
+    // Cache frequently accessed elements
+  }
+
+  // Public API methods
+}
+```
+### Component Categories
+
+#### Generic Components (Reusable across any project)
+- **NumberDisplay**: Generic numeric value display with animation, prefix/suffix, min/max
+- **ProgressBar**: Generic progress/status bars with themes and animations
+- **InventoryBar<T>**: Generic slot-based container with customizable item rendering
+- **InventoryGrid<T>**: Generic grid-based inventory with drag-and-drop
+- **Minimap**: Generic world view with configurable targets
+
+#### Specialized Components (Game-specific but commonly used)
+- **AmmoCounter**: FPS-specific ammunition display
+- **ReloadIndicator**: Reload progress indicator
+- **Crosshair**: FPS targeting reticle
+- **Compass**: Directional indicator
+
+### Generic Component Usage Examples
+
+#### NumberDisplay (replaces old PointsCounter)
+```typescript
+// For points/score
+const pointsDisplay = new ENGINE.NumberDisplay(ui, {
+  prefix: 'Points: ',
+  initialValue: 0,
+  animate: true,
+  animationDuration: 200
+});
+await pointsDisplay.initialize();
+pointsDisplay.setPosition({
+  position: 'absolute',
+  top: '20px',
+  right: '30px'
+}, '.number-display-container');
+
+// For health
+const healthDisplay = new ENGINE.NumberDisplay(ui, {
+  prefix: 'Health: ',
+  suffix: '%',
+  initialValue: 100,
+  minValue: 0,
+  maxValue: 100
+});
+await healthDisplay.initialize();
+healthDisplay.setPosition({
+  position: 'absolute',
+  top: '20px',
+  left: '20px'
+}, '.number-display-container');
+
+// API methods
+pointsDisplay.add(50, true); // Add 50 with animation
+healthDisplay.setValue(75); // Set to 75
+```
+
+#### ProgressBar with Flexible Positioning
+```typescript
+// Health bar with custom positioning
+const healthBar = new ENGINE.ProgressBar(ui, {
+  currentValue: 85,
+  maxValue: 100,
+  theme: 'health',
+  width: 200,
+  height: 20,
+  label: 'Health',
+  textDisplay: 'both',
+  style: 'gradient',
+  animate: true
+});
+await healthBar.initialize();
+healthBar.setPosition({
+  position: 'absolute',
+  top: '20px',
+  left: '20px'
+}, '.progress-bar-container');
+
+// Mana bar positioned below health
+const manaBar = new ENGINE.ProgressBar(ui, {
+  currentValue: 60,
+  maxValue: 120,
+  theme: 'mana',
+  width: 200,
+  height: 18,
+  label: 'Mana',
+  textDisplay: 'both',
+  style: 'glow',
+  animate: true
+});
+await manaBar.initialize();
+manaBar.setPosition({
+  position: 'absolute',
+  top: '70px', // Below health bar
+  left: '20px'
+}, '.progress-bar-container');
+```
+
+#### InventoryBar<T> with Custom Items
+```typescript
+// Define custom item type
+interface WeaponItem extends ENGINE.InventoryItem {
+  id: string;
+  weaponType: 'sword' | 'bow' | 'staff';
+  rarity: 'common' | 'rare' | 'epic';
+  iconUrl: string;
+}
+
+// Custom renderer for weapons
+const renderWeapon = (item: WeaponItem, slotElement: HTMLElement) => {
+  const content = slotElement.querySelector('.item-content') as HTMLElement;
+  if (content) {
+    content.innerHTML = `<img src="${item.iconUrl}" alt="${item.weaponType}">`;
+    content.className = `item-content weapon-${item.rarity}`;
+    content.title = `${item.weaponType} (${item.rarity})`;
+  }
+};
+
+const weaponInventory = new ENGINE.InventoryBar<WeaponItem>(ui, {
+  slotCount: 6,
+  itemRenderer: renderWeapon
+});
+await weaponInventory.initialize();
+weaponInventory.setPosition({
+  position: 'absolute',
+  bottom: '20px',
+  left: '50%',
+  transform: 'translateX(-50%)'
+}, '.inventory-bar');
+```
+
+## Modern Positioning System
+
+### setPosition() Method
+All UI components that extend `BaseUIComponent` have a flexible `setPosition()` method:
+
+```typescript
+// Basic positioning
+component.setPosition({
+  position: 'absolute',
+  top: '20px',
+  left: '20px'
+});
+
+// Centered positioning
+component.setPosition({
+  position: 'absolute',
+  top: '50%',
+  left: '50%',
+  transform: 'translate(-50%, -50%)'
+});
+
+// Target specific child elements
+component.setPosition({
+  position: 'absolute',
+  bottom: '20px',
+  right: '30px'
+}, '.component-container');
+
+// Complex positioning with viewport units
+component.setPosition({
+  position: 'fixed',
+  top: '10vh',
+  right: '5vw',
+  transform: 'translateY(-50%)'
+});
+```
+
+### CSS Structure (No Position Classes)
+```css
+/* ✅ Good - Base styling only */
+.component-container {
+  position: absolute;
+  pointer-events: none;
+  z-index: 1000;
+  user-select: none;
+  /* Visual styling only */
+  background: rgba(0, 0, 0, 0.7);
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-radius: 8px;
+  padding: 12px;
+}
+
+/* ❌ Bad - Don't include position variants */
+.component-container.top-left {
+  top: 20px;
+  left: 20px;
+}
+.component-container.bottom-right {
+  bottom: 20px;
+  right: 20px;
+}
+```
+
+## UI Element Management
+
+### Element Creation
+- Use `ui.createElement()` for simple elements
+- Use `ui.createLayout()` for complex components with templates
+- IDs are automatically generated by BaseUIComponent
+- Set `pointerEvents: 'none'` for HUD elements that shouldn't block game input
+
+### Component Integration
+```typescript
+// Initialize HUD components
+private async setupHUDComponents(ui: ENGINE.UIManager): Promise<void> {
+  // Create component without position option
+  this.ammoCounter = new ENGINE.AmmoCounter(ui, {
+    lowAmmoThreshold: 5,
+    showLowAmmoWarning: true
+  });
+  await this.ammoCounter.initialize();
+  
+  // Position using setPosition method
+  this.ammoCounter.setPosition({
+    position: 'absolute',
+    bottom: '30px',
+    right: '30px'
+  }, '.ammo-counter-container');
+
+  // Use NumberDisplay instead of deprecated PointsCounter
+  this.pointsDisplay = new ENGINE.NumberDisplay(ui, {
+    prefix: 'Score: ',
+    initialValue: 0,
+    animate: true
+  });
+  await this.pointsDisplay.initialize();
+  this.pointsDisplay.setPosition({
+    position: 'absolute',
+    top: '180px', // Below minimap
+    right: '30px'
+  }, '.number-display-container');
+
+  // ... other components
+}
+
+// Update components in game loop
+private updateHUD(): void {
+  this.ammoCounter.setAmmo(this.currentAmmo, this.maxAmmo);
+  this.pointsDisplay.add(50); // Use NumberDisplay API
+  this.compass.updateRotation(camera);
+  this.minimap.render();
+}
+
+// Cleanup components
+private cleanupHUD(): void {
+  this.ammoCounter?.destroy();
+  this.pointsDisplay?.destroy();
+  this.crosshair?.destroy();
+  // ... other components
+}
+```
+
+## Component Lifecycle
+
+### Initialization Pattern
+All components follow the same lifecycle:
+1. Create instance with options (no position option)
+2. Call `initialize()` method
+3. Call `setPosition()` to place the component
+4. Use component methods to update state
+5. Call `destroy()` when removing
+
+### Event Handling with UILayout
+```typescript
+// Use declarative event handling with UILayout
+const menuLayout = ui.createLayout('game-menu', {
+  template: menuTemplate,
+  styles: menuStyles,
+  eventHandlers: {
+    resume: {
+      selector: '#resume-btn',
+      event: 'click',
+      handler: () => this.toggleMenu()
+    },
+    restart: {
+      selector: '#restart-btn', 
+      event: 'click',
+      handler: () => this.restartGame()
+    }
+  }
+});
+
+// Or add handlers after creation
+menuLayout.onClick('#settings-btn', () => this.openSettings());
+menuLayout.onInput('#search-input', (element, event) => {
+  this.handleSearch(element.value);
+});
+
+// For game input, use engine's input system
+this.controller.onMouseDown.add((button: ENGINE.MouseButton, e: MouseEvent) => {
+  if (button === ENGINE.MouseButton.Left) {
+    this.handleAction();
+    return true; // Consume event
+  }
+  return false;
+});
+```
+
+## Common UI Patterns
+
+### Generic Numeric Displays
+```typescript
+// Score/points display with animation
+export class ScoreDisplay extends ENGINE.NumberDisplay {
+  constructor(ui: ENGINE.UIManager) {
+    super(ui, {
+      prefix: 'Score: ',
+      animate: true,
+      animationDuration: 300
+    });
+  }
+
+  public async initializeAndPosition(): Promise<void> {
+    await this.initialize();
+    this.setPosition({
+      position: 'absolute',
+      top: '20px',
+      left: '50%',
+      transform: 'translateX(-50%)'
+    }, '.number-display-container');
+  }
+}
+```
+
+### Custom Component with setPosition Support
+```typescript
+export class CustomPanel extends BaseUIComponent<CustomPanelOptions> {
+  protected getAssetPaths() {
+    return {
+      templatePath: '@engine/assets/ui/templates/custom-panel.html',
+      stylesPath: '@engine/assets/ui/styles/custom-panel.css'
+    };
+  }
+
+  // ... other required methods
+
+  /**
+   * Convenience method for specific positioning
+   */
+  public setCustomPosition(styles: Record<string, string>): void {
+    this.setPosition(styles, '.custom-panel-container');
+  }
+
+  /**
+   * Position at specific screen location
+   */
+  public positionAt(x: number, y: number): void {
+    this.setPosition({
+      position: 'absolute',
+      left: `${x}px`,
+      top: `${y}px`
+    }, '.custom-panel-container');
+  }
+}
+```
+
+### Progress Indicators
+```typescript
+export class ReloadIndicator extends BaseUIComponent<ReloadIndicatorOptions> {
+  public async startReload(): Promise<void> {
+    return new Promise((resolve) => {
+      const startTime = performance.now();
+      const duration = this.options.reloadDuration;
+
+      const updateProgress = (currentTime: number) => {
+        const elapsed = currentTime - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+        
+        this.updateProgressDisplay(progress);
+        
+        if (progress < 1) {
+          requestAnimationFrame(updateProgress);
+        } else {
+          resolve();
+        }
+      };
+      
+      requestAnimationFrame(updateProgress);
+    });
+  }
+}
+```
+
+## Performance Considerations
+
+### Efficient Updates
+- Use `requestAnimationFrame` for smooth animations
+- Cache DOM queries and element references
+- Batch DOM updates when possible
+- Use CSS transitions instead of JavaScript animations when appropriate
+- Update only when values change
+
+### Memory Management
+```typescript
+// Always clean up resources in BaseUIComponent
+protected override onDestroy(): void {
+  // Cancel any ongoing animations
+  if (this.animationId) {
+    cancelAnimationFrame(this.animationId);
+  }
+  
+  // Clear element references (handled by BaseUIComponent)
+  // Remove event listeners (handled by UILayout)
+}
+```
+
+## Error Handling
+
+### Robust Asset Loading
+```typescript
+// BaseUIComponent handles this pattern
+protected async loadAssets(): Promise<{ template: string; styles: string }> {
+  const { templatePath, stylesPath } = this.getAssetPaths();
+  try {
+    return await ENGINE.UIAssetLoader.loadUIAsset(templatePath, stylesPath);
+  } catch (error) {
+    throw new Error(`Failed to load UI assets for ${this.constructor.name}: ${error}`);
+  }
+}
+```
+
+## Deprecated Patterns
+
+### ❌ Avoid: Manual getComponentId() implementation
+```typescript
+// ❌ Old - manual ID generation (now unnecessary)
+protected getComponentId(): string {
+  return `my-component-${shortUUID()}`;
+}
+```
+
+### ✅ Use: Automatic ID generation
+```typescript
+// ✅ New - automatic ID generation from class name
+export class MyComponent extends BaseUIComponent<MyComponentOptions> {
+  // No getComponentId() needed!
+  // Automatically generates: "my-component-${shortUUID()}"
+  
+  protected getAssetPaths() { /* ... */ }
+  protected getDefaultOptions() { /* ... */ }
+  protected getInitialData() { /* ... */ }
+}
+```
+
+### ❌ Avoid: Position option in component constructor
+```typescript
+// ❌ Old - position as option (deprecated)
+const ammoCounter = new ENGINE.AmmoCounter(ui, {
+  position: 'bottom-right', // Don't use this
+  lowAmmoThreshold: 5
+});
+```
+
+### ✅ Use: setPosition() method
+```typescript
+// ✅ New - use setPosition() method
+const ammoCounter = new ENGINE.AmmoCounter(ui, {
+  lowAmmoThreshold: 5
+});
+await ammoCounter.initialize();
+ammoCounter.setPosition({
+  position: 'absolute',
+  bottom: '30px',
+  right: '30px'
+}, '.ammo-counter-container');
+```
+
+### ❌ Avoid: CSS positioning classes
+```typescript
+// ❌ Old - CSS classes for positioning
+.ammo-counter.bottom-right {
+  bottom: 30px;
+  right: 30px;
+}
+```
+
+### ✅ Use: Pure styling CSS
+```typescript
+// ✅ New - only visual styling in CSS
+.ammo-counter {
+  position: absolute;
+  background: rgba(0, 0, 0, 0.7);
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-radius: 8px;
+  padding: 12px;
+  /* No positioning properties */
+}
+```
+
+When generating UI code, always follow these patterns:
+1. Extend BaseUIComponent for all custom components
+3. Use setPosition() method for flexible positioning
+4. Keep CSS focused on visual styling only
+5. Initialize components before positioning them
+
+<reference_materials>
+# Below are additional materials you MUST digest in order to get complete understanding of the topic. Read them carefully.
+<file path={src/ui/UIManager.ts}>
+<file path={src/ui/components/AmmoCounter.ts}>
+<file path={src/ui/components/BaseUIComponent.ts}>
+<file path={src/ui/components/Compass.ts}>
+<file path={src/ui/components/ControlsPanel.ts}>
+<file path={src/ui/components/Crosshair.ts}>
+<file path={src/ui/components/InventoryBar.ts}>
+<file path={src/ui/components/InventoryGrid.ts}>
+<file path={src/ui/components/Minimap.ts}>
+<file path={src/ui/components/NumberDisplay.ts}>
+<file path={src/ui/components/ProgressBar.ts}>
+<file path={src/ui/components/ReloadIndicator.ts}>
+<file path={src/ui/ui-loader.ts}>
+</reference_materials>

package/docs/deprecated/Agents.md

@@ -0,0 +1,117 @@
+# Agents.md
+
+## Purpose
+
+This document defines the standards, practices, and expectations for AI agents (e.g., Codex) when operating on the Genesys codebase, particularly for tasks involving code annotation, documentation, and augmentation for AI-first development.
+
+## Mission
+
+The agent must operate with the primary objective of making the codebase accessible, understandable, and extensible to AI assistants and human developers alike.
+
+Each action should:
+
+- Maximize clarity.
+- Avoid generalizations.
+- Be *specific* and *contextual* to the code it is annotating.
+- Treat each file uniquely — no reusing or templating unless the files are *identical*.
+- Prioritize quality over speed.
+
+## Code Commenting Standard
+
+### General Guidelines
+
+1. **File-Level Descriptive Comments**
+   - Begin each `.ts` file with a block comment.
+   - Clearly describe the *purpose*, *behavior*, and *usage* of the code.
+   - Include practical usage advice for humans and AI assistants.
+   - Use the same depth and specificity as the examples provided.
+
+2. **Content Structure**
+
+Each comment block must have the following elements:
+
+- **High-Level Purpose**: What the file/code is for.
+- **Key Behaviors/Functionalities**: Major methods, classes, logic.
+- **Usage Recommendations**: How developers or AI should use, extend, or modify this code.
+
+### Example Format
+```ts
+/**
+ * [Class/Module/Component Name] [one-line description of the main purpose].
+ *
+ * [Detailed explanation]:
+ * - What it wraps or enhances.
+ * - How it interacts with the Genesys engine or scene.
+ * - Notable internal behaviors or constraints.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Practical tips and best practices.
+ * - Key properties or methods to use or override.
+ * - Common pitfalls and how to avoid them.
+ */
+```
+## Principles
+
+- **One file at a time**: Treat every file as unique.
+- **No copy-pasting**: Even similar files must have tailored comments.
+- **Think like an AI**: If you were an AI agent, what would you need to know to use or extend this code safely and effectively?
+- **No assumptions**: Explicitly state behaviors or dependencies that may seem obvious.
+- **Consistency**: Maintain a consistent style, tone, and detail level.
+- **Completeness**: Don’t skip files unless instructed.
+
+## Depth Requirement
+
+- Minimum of **5 sentences** per file-level comment.
+- For complex files, aim for **8–10 sentences**.
+- Avoid brevity unless the file is trivially small (e.g., type definitions, simple constants).
+
+## Branching Instructions
+
+- Always create a **new branch** from `develop` unless explicitly told otherwise.
+- Do not reuse previous test branches.
+- Name the branch based on the task and date, e.g., `feat/comment-enhancement-20250602`.
+
+## Agent Behavior Rules
+
+### Operating Mode
+
+- **Iterative and Careful**: Pause after every 10 files to validate the quality.
+- **No summarization shortcuts**: No high-level "This file does X" summaries unless deeply elaborated.
+- **No aggressive optimizations**: Focus on best-in-class documentation, not speed of execution.
+
+### Validation
+
+Before marking the task as complete:
+
+- Ensure each file has a **unique, detailed comment block**.
+- Perform a **redundancy check** — no two comments should be substantially similar unless file content demands it.
+
+## Failure Modes to Avoid
+
+- Reusing comments across non-identical files.
+- Oversimplified descriptions.
+- Lack of actionable usage tips.
+- Skipping files without explicit instruction.
+
+## Example Bad vs. Good Comments
+
+**Bad:**
+```ts
+/** CameraComponent - wraps a camera for use. */
+```
+***Good:***
+```ts
+/**
+ * CameraComponent wraps a THREE.Camera so it can be placed in the Genesys scene.
+ *
+ * Exactly one camera type must be configured—either perspective or orthographic—via the options provided at construction. 
+ * The internal camera is flagged as a THREE camera so `lookAt` works automatically and is exposed through the `camera` 
+ * property for direct manipulation.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use perspective mode for typical 3D gameplay; orthographic for isometric or UI views.
+ * - Retrieve `component.camera` to tweak properties like `zoom` or `aspect`.
+ * - Attach this component to the actor that should own the camera in the scene graph.
+ * - Combine with FollowComponent or custom scripts to animate or reposition the camera.
+ */
+```