# Copilot Instructions

## Project Overview

This is a **Defold game engine library** that implements **biplanar (world-space triplanar) texture mapping** for 3D models. It is distributed as a Defold library extension — consuming projects add it via `game.project`:

```ini
[library]
include_dirs = biplanar-mapping
```

The `biplanar-mapping/` directory is the publishable library. The `main/`, `materials/`, and `assets/` directories are demo/test content only.

## Architecture

### Library (`biplanar-mapping/`)
- `biplanar_instanced.vp` — Vertex shader. Passes world-space position and normal to the fragment stage. Uses instanced rendering (no `mtx_world` uniform — it comes in as a vertex attribute).
- `biplanar.fp` — Fragment shader. Implements biplanar mapping: samples `tex0` (side/rock) using world XZ projections, samples `tex1` (top/grass) using world XZ top-down UV, then blends by surface normal's Y component.
- `biplanar_instanced.material` — Wires up the shaders, declares fragment uniforms with defaults.

### Demo (`main/`, `materials/`, `assets/`)
- `main/cam.script` — Orbit camera controller (touch drag + mouse wheel zoom).
- `main/test.script` — Sets per-object material uniforms at init; demonstrates overriding defaults via `go.set()`.
- `materials/` — Supporting materials used by the demo (unlit instanced, tinted, skinned, UV repeat).

## Shader Uniforms

All uniforms live in named GLSL blocks (`vs_uniforms`, `fs_uniforms`) as required by Defold.

| Uniform | Type | Description |
|---|---|---|
| `texture_scale` | `vec4` | xyz = side texture scale per axis, w = top texture scale |
| `texture_params` | `vec4` | x = blend_start (normal.y), y = blend_end, z = ground_dark_start (world Y), w = ground_dark_end |
| `mid_params` | `vec4` | x = mid band center, y = mid band width, z = enable flag (1.0 = on) |
| `ground_color` | `vec4` | Color applied at/below ground_dark_start |
| `mid_color` | `vec4` | Color blended into the mid band when mid_params.z == 1 |

Override per object at runtime with `go.set("/go#model", "texture_scale", vmath.vector4(...))`.

## Key Conventions

- **GLSL version 140** is used across all shaders (`#version 140`).
- **Instanced rendering** is triggered automatically by Defold when `mtx_world` and `mtx_normal` are declared as `in mediump mat4` vertex attributes — do not add them as uniforms.
- **`VERTEX_SPACE_LOCAL`** is set in all materials; world transform is applied manually in the vertex shader.
- **Samplers** `tex0` (side) and `tex1` (top) use `WRAP_MODE_REPEAT` with linear filtering.
- **Biplanar vs triplanar**: the shader uses only X and Z side projections (no Y), normalized to sum to 1, for performance. The commented-out 3-sample path is preserved for reference.
- **`mid_params.z`** acts as a boolean enable: `0.0` disables the mid-band color overlay, `1.0` enables it.
- The `exclude_gles_sm100 = 1` setting in `game.project` disables legacy GLES SM1.0 shader compilation.

## Building

Defold projects are built and run through the **Defold Editor** (GUI) or via `bob.jar` (command-line build tool). There are no npm/make/cmake scripts. To build from the command line:

```sh
java -jar bob.jar --platform <platform> build
```
