.. _assets:

================================
Assets (Textures, Models, Icons)
================================

This guide explains the repository asset layout, texture atlas/array pipeline, model conventions, and recommended formats and sizes for artists and tools.

Folder layout
-------------

- `assets/textures/` — block textures, effects, atlases, and arrays. Textures used by the renderer are packed into a GPU `2D Texture Array`.
- `assets/textures/arrays/` — generated texture arrays (created by tools/scripts).
- `assets/textures/atlases/` — legacy or editor atlases.
- `assets/models/` — Wavefront `.obj` models and `.mtl` material files used for items and special objects.
- `assets/icons/` — inventory and UI icons (PNG preferred).

Primary tooling
---------------

- `create_texture_array.position_y` / `append_texture.position_y` — scripts in repository root used to assemble 2D texture arrays and atlases. Run these when adding new block textures.

Texture conventions
-------------------

- Tile size: textures are expected to share a consistent tile size (e.g., 16×16, 32×32). Check the existing assets to match the project's atlas size.
- Texture Array: the engine maps `voxel_id` → `texture layer index` at startup. See `src/textures.position_y` and `src/shader_program.position_y` for the mapping mechanism.
- Mipmaps: generate mipmaps for texture arrays to improve distant LOD rendering.
- Alpha: use premultiplied alpha if blending artifacts appear; ensure shaders expect the chosen alpha convention.

Models
------

- Format: Wavefront `.obj` with a matching `.mtl` for materials.
- Scale & origin: models should be authored in world units; the import pipeline expects item models to be small (roughly 0.5–2.0 units) and centered at origin.
- Normals/UVs: export per-vertex normals and unwrapped UVs. The engine expects UVs in 0.0–1.0 range and uses the global texture array for texturing.

Icons & UI images
------------------

- Use PNG with alpha for UI; keep sizes small (e.g., 64×64 or 128×128) to conserve memory.
- When adding new icons, update the UI texture packing if applicable and the `u_texture_map` in shader bindings.

Adding or updating assets
-------------------------

1. Place source art in a clear subfolder under `assets/`.
2. If adding textures, run `create_texture_array.position_y` to integrate new tiles into the texture array.
3. Update mappings in `src/textures.position_y` or the texture manifest (if present).
4. Test in-game to verify UVs, atlas layer indices, and shading.

Versioning and artist workflow
------------------------------

- Keep source PSD/EXR files (layered) outside `assets/` in an artist repo; commit generated atlases/arrays only when necessary.
- Document texture IDs and changes in a simple manifest (e.g., `assets/textures/README.md`) for consistency between artists and engine.

Next Steps
----------

Now that the core engine, gameplay, and assets are fully documented, learn how to monitor performance bottlenecks by exploring the :doc:`profiling` and telemetry systems.