### Shalloteer Imperative Usage - Setup (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

Provides an example of imperative usage within a Shalloteer system, specifically in the 'setup' function. It demonstrates getting built-in components, creating entities, adding components with data, querying entities, checking/removing components, and destroying entities.

```typescript
import * as GAME from 'shalloteer';

const Health = GAME.defineComponent({
  current: GAME.Types.f32,
  max: GAME.Types.f32
});

const MySystem: GAME.System = {
  setup: (state) => {
    // Get built-in components
    const Transform = state.getComponent('transform')!;
    
    // Create entity
    const entity = state.createEntity();
    
    // Add component with data
    state.addComponent(entity, Transform, {
      posX: 10, posY: 0, posZ: -5
    });
    
    // Query entities with both components
    const entities = state.query(Transform, Health);
    
    // Check/remove components
    if (state.hasComponent(entity, Health)) {
      state.removeComponent(entity, Health);
    }
    
    // Destroy entity
    state.destroyEntity(entity);
  }
};
```

--------------------------------

### Shalloteer Quick Start Example

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

This snippet demonstrates how to quickly set up and run a Shalloteer game. It includes loading the Shalloteer library from a CDN and defining a basic game world with a ground plane and a ball using the declarative HTML-like syntax.

```html
<script src="https://cdn.jsdelivr.net/npm/shalloteer@latest/dist/cdn/shalloteer.standalone.iife.js"></script>

<world canvas="#game-canvas" sky="0x87ceeb">
  <!-- Main Platform -->
  <static-part
    pos="0 -0.5 0"
    shape="box"
    size="20 1 20"
    color="0x90ee90"
  ></static-part>

  <!-- Ball -->
  <dynamic-part
    pos="-2 4 3"
    shape="sphere"
    size="1"
    color="0xff4500"
  ></dynamic-part>
</world>

<canvas id="game-canvas"></canvas>

<script>
  GAME.run();
</script>
```

--------------------------------

### Shalloteer Development Commands

Source: https://github.com/dylanebert/shalloteer/blob/main/README.md

Provides essential commands for developing with Shalloteer, including installing dependencies, running examples, building the library, and running tests.

```bash
# Install dependencies
bun install

# Run example
bun run example

# Build library (fast, library only)
bun run build

# Build for release (includes docs & CDN)
bun run build:release

# Run tests
bun test
```

--------------------------------

### Basic Rendering Setup with XML

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/rendering.md

Sets up a basic declarative scene using XML, including a canvas, sky color, default lighting, and rendered box and sphere entities with specified properties.

```xml
<!-- Declarative scene with lighting and rendered objects -->
<world canvas="#game-canvas" sky="0x87ceeb">
  <!-- Default lighting -->
  <light></light>
  
  <!-- Rendered box -->
  <entity 
    transform
    renderer="shape: box; color: 0xff0000; size-x: 2"
    pos="0 1 0"
  />
  
  <!-- Rendered sphere -->
  <entity
    transform
    renderer="shape: sphere; color: 0x00ff00"
    pos="3 1 0"
  />
</world>
```

--------------------------------

### Custom Lighting Setup with XML

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/rendering.md

Demonstrates custom lighting configurations in XML, including separate ambient and directional lights with properties for color, intensity, direction, and shadow casting.

```xml
<!-- Separate ambient and directional lights -->
<ambient-light 
  sky-color="0xffd4a3"
  ground-color="0x808080"
  intensity="0.4"
/>

<directional-light
  color="0xffffff"
  intensity="1.5"
  direction-x="-1"
  direction-y="3"
  direction-z="-0.5"
  cast-shadow="1"
  shadow-map-size="2048"
/>
```

--------------------------------

### Install Shalloteer with npm

Source: https://github.com/dylanebert/shalloteer/blob/main/README.md

Installs the Shalloteer game engine using npm. This is the first step to start using the engine in your project.

```bash
npm install shalloteer
```

--------------------------------

### Imperative Respawn Setup (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/respawn.md

Provides a TypeScript example of how to imperatively add a respawn component to an entity using the Shalloteer game engine API. It shows creating an entity, adding a Transform component, and then adding a Respawn component with specific coordinates.

```typescript
import * as GAME from 'shalloteer';

// Add respawn to an entity
const entity = state.createEntity();

// Set spawn point from current transform
state.addComponent(entity, GAME.Transform, {
  posX: 0, posY: 10, posZ: 0,
  eulerX: 0, eulerY: 0, eulerZ: 0
});

state.addComponent(entity, GAME.Respawn, {
  posX: 0, posY: 10, posZ: 0,
  eulerX: 0, eulerY: 0, eulerZ: 0
});

// Entity will respawn at (0,10,0) when falling
```

--------------------------------

### Register Multiple Plugins in Shalloteer

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

Demonstrates how to build a game application by registering multiple plugins. This example starts by disabling default plugins and then adds Transforms, Rendering, and Physics plugins.

```typescript
import * as GAME from 'shalloteer';

GAME
  .withoutDefaultPlugins()
  .withPlugin(TransformsPlugin)
  .withPlugin(RenderingPlugin)
  .withPlugin(PhysicsPlugin)
  .run();
```

--------------------------------

### Manual Plugin Registration

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/startup.md

Illustrates how to manually register specific Shalloteer plugins, including the StartupPlugin, while excluding default plugins for a more controlled initialization process.

```typescript
import * as GAME from 'shalloteer';

// Use startup plugin without other defaults
GAME.withoutDefaultPlugins()
  .withPlugin(GAME.TransformsPlugin)
  .withPlugin(GAME.RenderingPlugin) 
  .withPlugin(GAME.StartupPlugin)
  .run();
```

--------------------------------

### XML Example: Shorthand Attributes

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/recipes.md

Provides examples of shorthand attributes that automatically expand to specific component properties, simplifying XML definitions.

```xml
<!-- These expand to component properties -->
<entity pos="0 5 0"></entity>  <!-- Expands to transform.pos -->
<entity color="0xff0000"></entity>  <!-- Expands to renderer.color -->
```

--------------------------------

### Idempotent Startup Systems

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/startup.md

Explains and demonstrates the idempotent nature of Shalloteer's startup systems, which check for existing entities before creating them, ensuring they only run once effectively.

```typescript
import * as GAME from 'shalloteer';

// First run: Creates player, camera, lights
state.query(GAME.Player).length // 0 -> creates player

// Subsequent runs: Skips creation
state.query(GAME.Player).length // 1 -> skips creation
```

--------------------------------

### Customize Input Mappings

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/input.md

Provides an example of how to customize input mappings and mouse sensitivity before running the game. This allows for remapping keys and adjusting control behavior.

```typescript
import * as GAME from 'shalloteer';

// Modify before starting the game
GAME.INPUT_CONFIG.mappings.jump = ['Space', 'KeyX'];
GAME.INPUT_CONFIG.mappings.moveForward = ['KeyW', 'KeyZ', 'ArrowUp'];
GAME.INPUT_CONFIG.mouseSensitivity.look = 0.3;

GAME.run();

```

--------------------------------

### XML with Transform Sync for Respawn (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/respawn.md

Demonstrates how position and rotation attributes in XML can automatically update both the entity's transform and its respawn component. This simplifies setup by setting related properties simultaneously.

```xml
<!-- Position sets both transform and respawn -->
<player pos="5 3 -2" euler="0 90 0"></player>
```

--------------------------------

### Linear Interpolation (lerp) in TypeScript

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/core.md

Demonstrates how to perform linear interpolation for values like position. It shows a basic interpolation and a conceptual example for smooth animation over time.

```typescript
import * as GAME from 'shalloteer';

// Interpolate position
const startPos = 0;
const endPos = 10;
const progress = 0.5; // 50%

const currentPos = GAME.lerp(startPos, endPos, progress); // 5

// Smooth animation over time
function animate(deltaTime) {
  const speed = 0.1;
  position = GAME.lerp(position, target, speed * deltaTime);
}
```

--------------------------------

### Basic Usage: Auto-Create Entities

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/startup.md

Demonstrates the basic usage of Shalloteer where the plugin automatically creates default entities like player, camera, and lighting upon running the game.

```typescript
import * as GAME from 'shalloteer';

// This will create player, camera, and lighting automatically
GAME.run(); // Uses DefaultPlugins which includes StartupPlugin
```

--------------------------------

### Register Basic Input Plugin

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/input.md

Demonstrates how to register the basic input plugin for Shalloteer. This is the initial step to enable input handling in your game.

```typescript
import * as GAME from 'shalloteer';

GAME
  .withPlugin(GAME.InputPlugin)
  .run();
```

--------------------------------

### Prevent Auto-Creation with XML Configuration

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/startup.md

Shows how to prevent Shalloteer's automatic entity creation by defining custom entities, such as a player and lighting, within an XML configuration.

```xml
<world>
  <!-- Creating your own player prevents auto-creation -->
  <player pos="10 2 -5" speed="12" />
  
  <!-- Creating custom lighting prevents default lights -->
  <entity ambient="sky-color: 0xff0000" directional />
</world>
```

--------------------------------

### Install Shalloteer with NPM

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

Installs the Shalloteer game engine package using the Node Package Manager (NPM). This is the standard way to add Shalloteer to your project for development.

```bash
npm install shalloteer
```

--------------------------------

### Basic Player XML Configuration

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/player.md

Demonstrates the basic XML structure for defining a player entity in Shalloteer. The player is automatically created if not explicitly specified.

```xml
<world>
  <!-- Player auto-created if not specified -->
  <player pos="0 2 0" speed="6" jump-height="3" />
</world>
```

--------------------------------

### XML Example: Component String Format

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/recipes.md

Illustrates defining multiple properties for a component within a single attribute, separated by semicolons.

```xml
<!-- Multiple properties separated by semicolons -->
<entity transform="pos: 0 5 0; euler: 0 45 0; scale: 1.5"></entity>
```

--------------------------------

### TypeScript: Custom Plugin Integration

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/physics.md

Shows how to integrate custom plugins, specifically the `PhysicsPlugin`, into a Shalloteer application. It demonstrates initializing physics and running the application with the plugin included.

```typescript
import * as GAME from 'shalloteer';

// Initialize physics before running
await GAME.initializePhysics();

// Use with builder
GAME
  .withPlugin(GAME.PhysicsPlugin)
  .run();
```

--------------------------------

### Create Basic Entity (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/recipes.md

Demonstrates creating a basic entity in XML, with and without components like 'transform' and 'renderer'. This shows how to define an entity and its properties directly in the XML structure.

```xml
<!-- Create a basic entity with no components -->
<entity></entity>

<!-- Entity with transform component -->
<entity transform="pos: 0 5 0"></entity>

<!-- Entity with multiple components -->
<entity 
  transform="pos: 0 5 0; euler: 0 45 0"
  renderer="shape: box; color: 0xff0000"
/>
```

--------------------------------

### XML Example: Single Property

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/recipes.md

An example of how to define a single property, such as 'transform', within an XML entity tag.

```xml
<entity transform="scale: 2"></entity>
```

--------------------------------

### Create Default Orbit Camera (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/orbit-camera.md

This snippet shows the simplest way to create a default orbital camera using XML. It requires no additional parameters and sets up a basic camera.

```xml
<!-- Create default orbital camera -->
<camera />
```

--------------------------------

### Programmatic Orbit Camera Control (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/orbit-camera.md

Shows how to programmatically control an orbit camera using TypeScript within the Shalloteer engine. This example covers rotating the camera based on mouse input and zooming using the mouse wheel.

```typescript
import * as GAME from 'shalloteer';

const CameraControlSystem = {
  update: (state) => {
    const cameras = state.query(GAME.OrbitCamera);
    
    for (const camera of cameras) {
      // Rotate camera on input
      if (state.input.mouse.deltaX) {
        GAME.OrbitCamera.targetYaw[camera] += state.input.mouse.deltaX * 0.01;
      }
      
      // Zoom on scroll
      if (state.input.mouse.wheel) {
        GAME.OrbitCamera.targetDistance[camera] = Math.max(
          GAME.OrbitCamera.minDistance[camera],
          Math.min(
            GAME.OrbitCamera.maxDistance[camera],
            GAME.OrbitCamera.targetDistance[camera] - state.input.mouse.wheel * 0.5
          )
        );
      }
    }
  }
};
```

--------------------------------

### Shalloteer Minimal XML Example

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

A minimal example showcasing the basic structure of a Shalloteer game world. It defines a canvas and a world with a static ground plane and a dynamic ball, adhering to the XML structure rules.

```html
<world canvas="#game-canvas" sky="0x87ceeb">
  <!-- Ground -->
  <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="0x90ee90"></static-part>
  
  <!-- Ball -->
  <dynamic-part pos="-2 4 -3" shape="sphere" size="1" color="0xff4500"></dynamic-part>
</world>
```

--------------------------------

### Custom Player XML Configuration

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/player.md

Shows how to configure a player with custom properties like position, speed, jump height, rotation speed, and camera sensitivity using XML.

```xml
<world>
  <player 
    pos="5 1 -10"
    speed="8"
    jump-height="4"
    rotation-speed="15"
    camera-sensitivity="0.005"
  />
</world>
```

--------------------------------

### XML Example: Vector3 Properties

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/recipes.md

Demonstrates defining Vector3 properties like 'pos' with explicit x, y, z values or broadcasting a single value to all axes.

```xml
<!-- Explicit x, y, z -->
<entity transform="pos: 0 5 -3"></entity>

<!-- Broadcast single value -->
<entity transform="scale: 2"></entity>  <!-- Becomes scale: 2 2 2 -->
```

--------------------------------

### Register Player Plugin (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/player.md

Shows how to register the PlayerPlugin within the Shalloteer engine using TypeScript. This is a common step for enabling player-related functionalities.

```typescript
import * as GAME from 'shalloteer';

GAME
  .withPlugin(GAME.PlayerPlugin)  // Included in defaults
  .run();
```

--------------------------------

### XML Tween - Complex Animation Sequence

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/tweening.md

This example demonstrates a complex animation sequence for a platform, animating its X position, Y rotation, and scaling properties with different easing functions and loop types.

```xml
<!-- Platform with multiple animated properties -->
<kinematic-part pos="0 0 0" color="0xff0000">
  <!-- Position animation -->
  <tween target="transform.pos-x" from="-5" to="5" duration="3" loop="ping-pong"></tween>
  <!-- Rotation animation -->
  <tween target="transform.euler-y" to="360" duration="10" loop="loop"></tween>
  <!-- Scale pulse -->
  <tween target="transform.scale-x" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
  <tween target="transform.scale-z" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
</kinematic-part>
```

--------------------------------

### XML Example: Euler Angles

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/recipes.md

Shows how to define rotation using Euler angles in degrees, which are automatically converted to quaternions.

```xml
<!-- Degrees, automatically converted to quaternion -->
<entity transform="euler: 0 45 0"></entity>
<entity transform="rotation: 0 45 0"></entity>  <!-- Alias for euler -->
```

--------------------------------

### Custom Orbit Camera Settings (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/orbit-camera.md

This example illustrates how to apply custom orbit camera settings directly within an entity's attributes using XML. It allows fine-tuning of target, distance, rotation, smoothness, and offset.

```xml
<entity 
  orbit-camera="
    target: #boss;
    target-distance: 15;
    target-yaw: 0;
    target-pitch: 0.5;
    smoothness: 0.2;
    offset-y: 3
  "
  transform
  main-camera
/>
```

--------------------------------

### JavaScript API: Error Handling (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/recipes.md

Provides an example of error handling when using the Shalloteer JavaScript API, specifically when attempting to create an entity from an unknown recipe. It shows how to catch errors and access informative messages.

```typescript
import * as GAME from 'shalloteer';

try {
  // This will throw with helpful message
  GAME.createEntityFromRecipe(state, 'unkown-recipe', {});
} catch (error) {
  console.error(error.message);
  // Output: Unknown element <unkown-recipe> - did you mean <unknown-recipe>?
  // Available recipes: entity, static-part, dynamic-part...
}
```

--------------------------------

### Run Shalloteer Game (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

Demonstrates how to import and run the Shalloteer game engine in a TypeScript project. It assumes the 'shalloteer' package has been installed.

```typescript
import * as GAME from 'shalloteer';
GAME.run();
```

--------------------------------

### Imperative Entity Creation with TypeScript

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/rendering.md

Shows how to create and configure entities programmatically using TypeScript. It involves adding transform and renderer components, and setting the canvas element for rendering.

```typescript
import * as GAME from 'shalloteer';

// Create rendered entity programmatically
const entity = state.createEntity();

// Add transform for positioning
state.addComponent(entity, GAME.Transform, {
  posX: 0, posY: 5, posZ: 0
});

// Add renderer component
state.addComponent(entity, GAME.Renderer, {
  shape: 1,        // sphere
  sizeX: 2,
  sizeY: 2,
  sizeZ: 2,
  color: 0xff00ff,
  visible: 1
});

// Set canvas for rendering context
const contextEntity = state.query(GAME.RenderContext)[0];
const canvas = document.getElementById('game-canvas');
GAME.setCanvasElement(contextEntity, canvas);
```

--------------------------------

### TypeScript Transforms: Setting Transform Values Directly

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/transforms.md

Provides examples of directly setting transform component values using a bitECS-style syntax in TypeScript. This includes setting position, Euler angles for rotation, and uniform scale.

```typescript
import * as GAME from 'shalloteer';

// Direct property access (bitECS style)
GAME.Transform.posX[entity] = 10;
GAME.Transform.posY[entity] = 5;
GAME.Transform.posZ[entity] = -3;

// Using euler angles for rotation
GAME.Transform.eulerX[entity] = 0;
GAME.Transform.eulerY[entity] = 45;
GAME.Transform.eulerZ[entity] = 0;
// Quaternion will be auto-synced by TransformHierarchySystem

// Uniform scale
GAME.Transform.scaleX[entity] = 2;
GAME.Transform.scaleY[entity] = 2;
GAME.Transform.scaleZ[entity] = 2;
```

--------------------------------

### Player with Automatic Respawn (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/respawn.md

Demonstrates how the `<player>` tag in XML automatically includes respawn functionality. The 'pos' attribute sets the initial spawn point and the respawn location.

```xml
<world>
  <!-- Player spawns at 0,5,0 and respawns there if falling -->
  <player pos="0 5 0"></player>
</world>
```

--------------------------------

### Create Parent-Child Hierarchies (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/recipes.md

Shows how to establish parent-child relationships between entities in XML. Children entities inherit the transform properties of their parent entities, enabling hierarchical scene structures.

```xml
<!-- Parent with children -->
<entity transform="pos: 0 0 0">
  <!-- Children inherit parent transform -->
  <entity transform="pos: 2 0 0"></entity>
  <entity transform="pos: -2 0 0"></entity>
</entity>

<!-- Nested hierarchy -->
<entity id="root" transform>
  <entity id="arm" transform="pos: 0 2 0">
    <entity id="hand" transform="pos: 0 2 0"></entity>
  </entity>
</entity>
```

--------------------------------

### TypeScript: Handle Collisions

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/physics.md

Demonstrates how to handle collisions in Shalloteer using a system that queries for `TouchedEvent`. It logs collided entities and applies an impulse in response to a collision.

```typescript
import * as GAME from 'shalloteer';

const CollisionSystem: GAME.System = {
  update: (state) => {
    // Query entities with collision events
    for (const entity of state.query(GAME.TouchedEvent)) {
      const otherEntity = GAME.TouchedEvent.other[entity];
      console.log(`Entity ${entity} collided with ${otherEntity}`);
      
      // React to collision
      state.addComponent(entity, GAME.ApplyImpulse, {
        x: 0, y: 10, z: 0
      });
    }
  }
};

```

--------------------------------

### Read Player Input in Custom System

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/input.md

Shows how to read player input within a custom game system. It accesses movement axes and button states for each player.

```typescript
import * as GAME from 'shalloteer';

const PlayerControlSystem: GAME.System = {
  update: (state) => {
    const players = state.query(GAME.Player, GAME.InputState);
    
    for (const player of players) {
      // Read movement axes
      const moveX = GAME.InputState.moveX[player];
      const moveY = GAME.InputState.moveY[player];
      
      // Check for jump
      if (GAME.InputState.jump[player]) {
        // Jump is available this frame
      }
      
      // Check mouse buttons
      if (GAME.InputState.leftMouse[player]) {
        // Left mouse is held
      }
    }
  }
};

```

--------------------------------

### Define Custom Component Properties (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/recipes.md

Shows how to define custom properties for components in XML, including enum-like values, vector properties that can broadcast changes, and deprecated quaternion properties.

```xml
<!-- Component with enum values -->
<entity body="type: dynamic"></entity>

<!-- Vector properties with broadcast -->
<entity transform="scale: 2"></entity>  <!-- All axes set to 2 -->

<!-- Quaternion (deprecated, use euler instead) -->
<entity transform="rot: 0 0 0 1"></entity>
```

--------------------------------

### Shalloteer Entity with Components (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

An example of creating an entity with multiple components defined directly in the XML. It includes transform, body, collider, and renderer components with specific properties.

```xml
<entity 
  transform="pos: 0 2 0"
  body="type: dynamic"
  collider="shape: sphere"
  renderer="color: 0xff0000"
/>
```

--------------------------------

### Manual Respawn Component (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/respawn.md

Shows how to manually add a respawn component to an entity using XML. The 'respawn' attribute specifies the position where the entity should respawn, typically when it falls below a certain threshold.

```xml
<entity transform body collider respawn="pos: 0 10 -5">
  <!-- Entity respawns at 0,10,-5 when falling below Y=-100 -->
</entity>
```

--------------------------------

### Consume Buffered Input Actions

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/input.md

Illustrates how to consume buffered input actions like jumping or primary attacks. Consuming actions prevents them from being triggered multiple times in a single frame.

```typescript
import * as GAME from 'shalloteer';

const CombatSystem: GAME.System = {
  update: (state) => {
    // Consume jump if available (prevents double consumption)
    if (GAME.consumeJump()) {
      // Perform jump
      velocity.y = JUMP_FORCE;
    }
    
    // Consume primary action
    if (GAME.consumePrimary()) {
      // Fire weapon
      spawnProjectile();
    }
  }
};

```

--------------------------------

### XML: Moving Platform

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/physics.md

Defines a kinematic physics entity (a platform) in XML that moves using a tweening component. It specifies position, shape, size, color, and a tween to animate its vertical position.

```xml
<kinematic-part
  pos="0 2 0"
  shape="box"
  size="3 0.2 3"
  color="0x4169e1"
>
  <!-- Add movement with tweening -->
  <tween
    target="body.pos-y"
    from="2"
    to="5"
    duration="3"
    ease="sine-in-out"
    loop="ping-pong"
  />
</kinematic-part>
```

--------------------------------

### Shalloteer Plugin API Reference

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/startup.md

Defines the StartupPlugin, a bundle of systems responsible for creating default game entities upon startup. It integrates lighting, camera, player, and character systems.

```TypeScript
type Plugin = any;

interface StartupPlugin extends Plugin {
    systems: [
        "LightingStartupSystem",
        "CameraStartupSystem",
        "PlayerStartupSystem",
        "PlayerCharacterSystem"
    ];
    components: [];
    description: "Bundle of systems that create default game entities on startup";
}
```

--------------------------------

### XML Tween - Animate Multiple Properties (Rotation)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/tweening.md

This example demonstrates animating the rotation property of an entity on all axes over 4 seconds with a continuous loop.

```xml
<!-- Animate rotation on all axes -->
<entity transform renderer>
  <tween 
    target="rotation" 
    to="0 360 0" 
    duration="4" 
    loop="loop"
  />
</entity>
```

--------------------------------

### Shalloteer CameraStartupSystem

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/startup.md

Sets up the main camera with orbit controls if no main camera exists in the scene. It creates an entity with MainCamera, OrbitCamera, and Transform components, configuring default distance, pitch, rotation, and smoothness.

```TypeScript
interface CameraStartupSystem {
    group: 'setup';
    purpose: 'Creates main camera with orbit controls if none exists';
    creates: 'One entity with MainCamera, OrbitCamera, and Transform components';
    condition: 'Only runs if no MainCamera exists';
    defaults: {
        distance: 10;
        pitch: -30;
        fullRotation: true;
        smoothness: 0.15;
    };
}
```

--------------------------------

### XML Tween - Animate Body Physics Velocity

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/tweening.md

This example animates the X velocity of a dynamic part's physics body from 0 to 10 over 1 second using quadratic-out easing.

```xml
<!-- Animate physics body velocity -->
<dynamic-part pos="0 10 0">
  <tween 
    target="body.velocity-x" 
    from="0" 
    to="10" 
    duration="1" 
    ease="quad-out"
  />
</tween>
```

--------------------------------

### Basic XML Tween - Animate Y Position

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/tweening.md

This example shows a basic XML tween to animate the Y position of a kinematic part from 5 to 10 over 2 seconds with a sine-in-out easing and ping-pong loop.

```xml
<!-- Animate Y position from 5 to 10 over 2 seconds -->
<kinematic-part pos="0 5 -5">
  <tween 
    target="transform.pos-y" 
    from="5" 
    to="10" 
    duration="2" 
    ease="sine-in-out" 
    loop="ping-pong"
  />
</kinematic-part>
```

--------------------------------

### Quaternion Interpolation (slerp) in TypeScript

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/core.md

Illustrates how to use spherical linear interpolation (slerp) for rotating objects smoothly between two orientations. It includes an example of interpolating between an identity quaternion and a 90-degree rotation.

```typescript
import * as GAME from 'shalloteer';

// Interpolate rotation
const from = { x: 0, y: 0, z: 0, w: 1 }; // Identity
const to = { x: 0, y: 0.707, z: 0, w: 0.707 }; // 90° Y rotation

const result = GAME.slerp(
  from.x, from.y, from.z, from.w,
  to.x, to.y, to.z, to.w,
  0.5 // 50% between rotations
);
// result is halfway rotation (45° Y)
```

--------------------------------

### XML Declaration for Animated Character Entity

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/animation.md

Provides an example of how to declare an entity with animated character properties using XML. This declaration includes the animated-character, character-controller, and transform components, specifying the position.

```xml
<!-- Player entity with animated character -->
<entity 
  animated-character
  character-controller
  transform="pos: 0 2 0"
/>
```

--------------------------------

### Shalloteer PlayerStartupSystem

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/startup.md

Creates a fully functional player entity if no player entities exist. This system adds essential components like Player, CharacterMovement, Transform, Body, Collider, CharacterController, InputState, and Respawn, with default position and collider settings.

```TypeScript
interface PlayerStartupSystem {
    group: 'setup';
    purpose: 'Creates a fully-functional player entity if none exists';
    creates: 'One entity with complete player setup';
    componentsAdded: [
        'Player',
        'CharacterMovement',
        'Transform',
        'Body',
        'Collider',
        'CharacterController',
        'InputState',
        'Respawn'
    ];
    condition: 'Only runs if no Player entities exist';
    defaults: {
        position: { x: 0, y: 5, z: 0 };
        collider: 'capsule';
        body: 'kinematic';
    };
}
```

--------------------------------

### TypeScript: Apply Forces

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/physics.md

Shows how to apply forces and impulses to physics entities using the Shalloteer JavaScript API. Examples include applying an upward impulse for a jump and a continuous force for acceleration, as well as directly setting linear velocity.

```typescript
import * as GAME from 'shalloteer';

// Apply upward impulse (jump)
state.addComponent(entity, GAME.ApplyImpulse, {
  x: 0, y: 50, z: 0
});

// Apply continuous force
state.addComponent(entity, GAME.ApplyForce, {
  x: 10, y: 0, z: 0
});

// Set velocity directly
state.addComponent(entity, GAME.SetLinearVelocity, {
  x: 0, y: 5, z: 0
});
```

--------------------------------

### Shalloteer LightingStartupSystem

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/reference/startup.md

Initializes default lighting for the scene if no lights are present. It creates entities with Ambient and Directional light components, applying specific default values for color and intensity.

```TypeScript
interface LightingStartupSystem {
    group: 'setup';
    purpose: 'Creates default lighting if no lights exist';
    creates: 'One entity with both Ambient and Directional light components';
    condition: 'Only runs if no Ambient or Directional lights exist';
    defaults: {
        ambient: {
            skyColor: '0xb0e0ff';
            groundColor: '0x4a3f2a';
            intensity: 0.6;
        };
        directional: {
            color: '0xffffff';
            intensity: 1.0;
            castsShadows: true;
            direction: 'down-forward';
        };
    };
}
```

--------------------------------

### Create Player Programmatically (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/player.md

Demonstrates the programmatic creation of a player entity in Shalloteer using TypeScript. It involves creating an entity and adding necessary components like Player, Transform, Body, CharacterController, and InputState.

```typescript
import * as GAME from 'shalloteer';

const PlayerSpawnSystem: GAME.System = {
  setup: (state) => {
    // Create player entity
    const player = state.createEntity();
    
    // Add player recipe components
    state.addComponent(player, GAME.Player, {
      speed: 7,
      jumpHeight: 3.5,
      cameraSensitivity: 0.01
    });
    
    // Add required components
    state.addComponent(player, GAME.Transform, { posY: 5 });
    state.addComponent(player, GAME.Body, { type: GAME.BodyType.KinematicPositionBased });
    state.addComponent(player, GAME.CharacterController);
    state.addComponent(player, GAME.InputState);
  }
};
```

--------------------------------

### Programmatic Tween - Create Tween in System

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/tweening.md

This TypeScript example shows how to programmatically create a tween within a Shalloteer system. It animates the Y position of an entity's transform from 0 to 10 over 2 seconds with a bounce-out easing and a single loop.

```typescript
import * as GAME from 'shalloteer';

// In a system
const MySystem = {
  setup: (state) => {
    const entity = state.createEntity();
    state.addComponent(entity, GAME.Transform);
    
    // Create tween programmatically
    GAME.createTween(state, entity, 'transform.pos-y', {
      from: 0,
      to: 10,
      duration: 2,
      easing: 'bounce-out',
      loop: 'once'
    });
  }
};
```

--------------------------------

### Orbit Camera Following Player (XML)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/orbit-camera.md

Demonstrates how to configure an orbit camera to follow a specific player entity in XML. It uses the 'target' attribute to link the camera to the player and sets distance and offset parameters.

```xml
<world>
  <!-- Player entity -->
  <player id="player" pos="0 0 0" />
  
  <!-- Camera following player -->
  <camera 
    target="#player"
    target-distance="10"
    min-distance="5"
    max-distance="20"
    offset-y="2"
  />
</world>
```

--------------------------------

### JavaScript API: Create and Parse Entities (TypeScript)

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/recipes.md

Demonstrates using the Shalloteer JavaScript API to create entities from recipes and parse XML structures into entities. It also shows how to convert Euler angles to quaternions.

```typescript
import * as GAME from 'shalloteer';

// Create entity from recipe
const entity = GAME.createEntityFromRecipe(state, 'entity', {
  pos: '0 5 0',
  color: '0xff0000'
});

// Parse XML to entities
const xmlElement = {
  tagName: 'entity',
  attributes: { transform: 'pos: 0 5 0' },
  children: []
};
const results = GAME.parseXMLToEntities(state, xmlElement);

// Convert Euler to quaternion
const quat = GAME.fromEuler(0, Math.PI / 4, 0);  // 45 degrees on Y
```

--------------------------------

### TypeScript: Create Physics Entity

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/physics.md

Demonstrates creating a dynamic physics box entity using the Shalloteer JavaScript API. It shows how to create an entity and add `Body` and `Collider` components with specific properties.

```typescript
import * as GAME from 'shalloteer';

// Create a dynamic physics box
const entity = state.createEntity();

state.addComponent(entity, GAME.Body, {
  type: GAME.BodyType.Dynamic,
  mass: 5,
  posX: 0, posY: 10, posZ: 0
});

state.addComponent(entity, GAME.Collider, {
  shape: GAME.ColliderShape.Box,
  sizeX: 1, sizeY: 1, sizeZ: 1,
  friction: 0.7,
  restitution: 0.3
});

// Note: Physics body won't exist until next fixed update
// Transform will be overwritten by Body position after initialization
```

--------------------------------

### Shape Types and Usage with TypeScript

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/rendering.md

Illustrates the available shape types in Shalloteer using TypeScript enums and demonstrates their usage in both XML and TypeScript code for entity rendering.

```typescript
import * as GAME from 'shalloteer';

// Available shape enums
const shapes = {
  box: 0,
  sphere: 1,
  cylinder: 2,
  plane: 3
};

// Use in XML
<entity renderer="shape: sphere"></entity>

// Or with enum names
<entity renderer="shape: 1"></entity>
```

--------------------------------

### Handle Input Events Manually

Source: https://github.com/dylanebert/shalloteer/blob/main/docs/examples/input.md

Demonstrates how to manually handle input events by attaching Shalloteer's exported event handlers to DOM elements like a canvas.

```typescript
import * as GAME from 'shalloteer';

// Use the exported handlers directly if needed
canvas.addEventListener('mousedown', GAME.handleMouseDown);
canvas.addEventListener('mouseup', GAME.handleMouseUp);

```

--------------------------------

### Define and Use Custom Components in Shalloteer

Source: https://github.com/dylanebert/shalloteer/blob/main/llms.txt

Demonstrates how to define a custom component with specific types (f32) and integrate it into a game system. The example shows creating a component, updating its properties within a system based on time delta, and registering it as a plugin.

```typescript
import * as GAME from 'shalloteer';

// Define component
const MyComponent = GAME.defineComponent({
  value: GAME.Types.f32,
  speed: GAME.Types.f32
});

// Define system
const MySystem: GAME.System = {
  update: (state) => {
    const entities = state.query(MyComponent);
    for (const entity of entities) {
      MyComponent.value[entity] += MyComponent.speed[entity] * state.time.delta;
    }
  }
};

// Create plugin
const MyPlugin: GAME.Plugin = {
  components: { MyComponent },
  systems: [MySystem],
  config: {
    defaults: {
      "my-component": { value: 0, speed: 1 }
    }
  }
};

// Register and run
GAME.withPlugin(MyPlugin).run();
```