Asset Goes Here Docs Sign in
ContentsBest practices for ids, tags and made-by
Request and review

Best practices for ids, tags and made-by

Every asset carries a few fields besides its file: an id, a kind, tags, where players see it, and how it was made. Asset Goes Here uses them to group the Library, decide who can claim what, scope guest links and fill in the AI disclosure. Choosing them well from the first request keeps a project easy to work in when it reaches hundreds or thousands of assets. This page says what each field is for and how to choose values for it. The second half covers strings files and translations.

The short version

FieldUse it forExample
idWhere the asset sits in the project: area, then subject, then the one assetchar.mira.portrait_worried
kindWhat kind of file to makeimage, audio, strings
TagsWhat the asset is and who it is for, across areas. Queues, reservations and guest links match themrole=portrait, character=mira
used_inWhere players see itgame, store, marketing
Provenance and made_byHow the file was made, and by what or whomai-assisted, Flux, retouched by Jane

As a rule of thumb, the id says where an asset lives, tags say what it is and who it is for, and made-by says who or what made it.

Ids and prefixes

An id is lowercase words of letters, digits and underscores, separated by dots, such as card.ember_wolf.art. It can't be changed once the asset exists, and it doesn't have to match the file's path, so choose it for how you want to browse the project rather than to copy your folders.

Read an id from left to right as a path through the project:

What prefixes drive

Good habits

Tags

A tag is a key=value pair, such as role=card_art. Keys and values are stored in lowercase with spaces trimmed from the ends. An asset has one value per key and at most 20 tags, with keys up to 64 characters and values up to 128.

Keys worth having

KeyWhat it saysExample values
roleWhat the asset does in the gamecard_art, portrait, backdrop, icon, dialogue, bark, lore, ui_label
characterWho it shows, or who speaks or voices itmira, bram
creature, location, factionYour game's own nounsember_wolf, kesterholm
act, chapter, milestoneWhen it is neededact_1, demo, launch

Use role rather than wishing for more kinds. A kind tells the maker what file to produce (image, audio, text, strings, model or file); role tells them what it is for. A portrait and a backdrop are both images, and dialogue and UI labels are both strings.

A few keys mean something to Asset Goes Here itself:

What tags drive

Good habits

A prefix, a tag, or both?

The Library's filter panel has two sides that never combine, so every count it shows is exactly how many assets a pick lists:

Choose with that in mind:

The CLI and API combine every filter freely, such as agh list --prefix char.bram. --tag role=portrait --status delivered. The panel keeps the two sides apart only so its counts stay exact.

Where players see it: used_in

used_in is game (the default), store or marketing. Steam's AI disclosure covers store pages and marketing as well as the game, and the disclosure report files store and marketing material by this field. Set it on capsule art, store screenshots, trailers and press images when you request them.

How it was made: provenance and made_by

Provenance is human, ai-assisted, ai or unknown. ai-assisted covers a person reworking AI output and AI reworking a person's work. made_by is free text naming the tool, model, service or person. Both are written to .agh/provenance.yaml with each published file, and the AI disclosure lists every distinct made_by behind AI and AI-assisted files, so the names you choose are the names the public may read.

Strings files and translations

Writing comes in two kinds. Use strings for keyed lines the game looks up, such as UI labels, item names, barks and dialogue by id. Use text for a whole piece of writing read as one, such as a lore entry or a store blurb. Tag either with a role, such as role=dialogue or role=ui_label. Writing and translations lists the formats each kind reads.

How much goes in one file

Each strings file is one asset, with its own claim, review, conversation and one translation per language. Size the files around how the writing gets done:

Keys

Revise keys, not files

To change a few lines, ask for a new version of just those keys:

agh revise localization.story.act_1 --note "Mira is angrier here; she has just found the cart empty" \
      --key comic.the_village_p3.panel_2.balloon_1 --key comic.the_village_p3.panel_3.caption

On the web, open the asset in the Library and choose Ask for a new version. For a strings file the form lists every key with its current text, in file order, with a search box that matches the key or the text; tick the lines, or choose + Add a new key. The writer reads those lines and their neighbours (agh strings <id> --around 1), and the reviewer is warned if a key outside the list changed or a chosen key was left alone. See Revising an asset.

Translations

A worked example: dialogue for a comic

A story game shows its scenes as comic pages, with a balloon or caption per line. Its dialogue is organized like this, and it has held up well:

Rewriting a scene then goes like this:

For agents: this page as Markdown is at /docs/metadata.md, and the CLI prints it with agh guide metadata.