gatos.paint_texture

tool Debug and rendering

List, inspect, retrieve, chunk-upload, or delete the custom ground-clutter texture store.

Use when: Managing uploaded images and discovering overridable stock clutter textures, separately from the bindings themselves.
Availability: paint_textures_enabled and TextureStore limits.

Input

Field	Type	Requirement	Description
`operation`	`string`	Required	list, catalog, bindings, retrieve, upload, or delete.
`name`	`string \| null`	Optional · null	Uploaded image name for retrieve, upload, or delete.
`offset`	`integer`	Optional · 0	Decoded byte offset for an upload chunk.
`complete`	`boolean`	Optional · true	Finalize the upload after this chunk.
`data_base64`	`string \| null`	Optional · null	Base64-encoded image bytes for upload.

Operation call shapes

Choose an operation below. Its required payload and a complete call stay together—there is no second table to cross-reference.

`list`

List uploaded images with name, bytes, sniffed container kind, version, and ready.

Arguments for this operation

{ operation: "list" }

Example

gatos.paint_texture({"operation":"list"})

`catalog`

List every overridable stock clutter texture: id, slot, size, mip count, used_by, and ecotypes. The only source of the texture ids paint_control texture_bind takes.

Arguments for this operation

{ operation: "catalog" }

Example

gatos.paint_texture({"operation":"catalog"})

`bindings`

Return desired bindings with their render mode (faithful or raw) alongside applied state, including per-binding pending/applied/failed status and error text.

Arguments for this operation

{ operation: "bindings" }

Example

gatos.paint_texture({"operation":"bindings"})

`retrieve`

Return metadata plus the stored bytes as an embedded binary resource at gatos://paint/textures/<name>.

Arguments for this operation

{ operation: "retrieve", name }

Example

gatos.paint_texture({"operation":"retrieve","name":"rock.png"})

`upload`

Write a bounded base64 chunk through TextureStore; the image becomes bindable when complete.

Arguments for this operation

{ operation: "upload", name, data_base64, offset?: decoded_byte_offset, complete?: boolean }

Example

gatos.paint_texture({"operation":"upload","name":"rock.png","data_base64":"iVBORw0KGgo=","offset":0,"complete":true})

`delete`

Evict an upload, unbinding it first.

Arguments for this operation

{ operation: "delete", name }

Example

gatos.paint_texture({"operation":"delete","name":"rock.png"})

Call example

gatos.paint_texture({"operation":"catalog"})

Result

Store metadata, catalog rows, or binding state; retrieve additionally emits an embedded binary resource.

Errors

ENOENT for an unknown image or stock texture id; EBUSY for a name that has not finished uploading; EFBIG/ENOSPC/EEXIST/EPERM for store limits; EINVAL for a bad name, malformed base64, or an unrecognized image container.
EOPNOTSUPP when paint_textures_enabled is false.

Operational notes

Accepted containers are png, jpeg, bmp, hdr, dds, ktx, and ktx2, sniffed from the bytes rather than the file extension.
Base64 inflates payloads by 4/3 and the request framing limit is 24 MiB; chunk uploads by decoded byte offset.
Clutter diffuse maps are modulation maps, not albedo: the shader doubles the texel and alpha selects sRGB/linear decoding and terrain-tint reach rather than opacity. The default faithful bind mode corrects for both, so an ordinary sRGB PNG renders as authored; raw is the opt-out for replacing a stock texture like-for-like.
Bind with gatos.paint_control(operation:"texture_bind", target, file, value:0|1); binding re-points a shared texture asset, so check used_by in the catalog first.