Game asset naming & format convention

Contract

Every game asset file (texture, audio, data) gets a filename built from a fixed, category-first token grammar with a context-specific file format. Apply it whenever you are asked to name, save, or rename an asset file — produce one exact filename, never an ad-hoc or descriptive name.

Rules

Texture / art files

Pattern, exact order, underscore-separated:

category_name_variant_size.ext

1. category — FIRST token, one of exactly these six: character, prop,

environment, ui, fx, tile. No synonyms (char, enemy, bg, vfx, terrain, icon are all wrong — map them to the canonical token).

1. name — the lowercase subject of the asset: goblin, sword, crate,

closebutton. A single token, no internal separator.

1. variant — the visual variant: red, damaged, night, pressed, gold.

If the asset has no variant, use the literal token base — never omit the slot.

1. size — the texture's pixel dimension as a power-of-two INTEGER, one of:

64, 128, 256, 512, 1024, 2048, 4096. Never a word (small, large, hi, sm), never a non-power-of-two, never 512x512 (just 512). Textures are square, so one number covers both dimensions.

1. .ext — chosen by destination, not by source format:

• UI / 2D-overlay / HUD textures → .png
• 3D / model / world / level textures → .ktx2 (compressed)
• Never .jpg, .jpeg, .tga, .bmp, .psd for shipped textures.

Audio files

Pattern, exact order — note context is SECOND and there is no size token:

category_context_name_variant.ext

1. category — FIRST token, one of exactly: sfx, music, voice, ambient.
2. context — SECOND token, the gameplay context: combat, ui, world, menu.
3. name — the lowercase subject: sword_swing becomes the name (+ optional

variant) portion; e.g. swing, click, footsteps, title.

1. variant — optional trailing variant (loop, alt, heavy). Omit if none —

audio does NOT require a base filler the way textures do.

1. .ext — always .ogg, for every audio category including music. Never .wav,

.mp3, .aiff, .flac.

Data files

snake_case_name.json

• snake_case lowercase words joined by underscores, .json extension.
• Example: enemy_stats.json, loot_table.json. Never .yaml/.yml/.xml for these,

never enemyStats.json or enemy-stats.json.

Universal rules (all asset types)

• All lowercase. Always.
• Separators are underscores ONLY — no spaces, no hyphens, no camelCase, no PascalCase,

no dots except the single extension dot.

• Texture dimensions are square and power-of-two; the size token is the integer edge length.

Worked examples (BEFORE = bare default, AFTER = conforming)

Texture, character with variant, 3D model, 512px

• BEFORE: GoblinRed.png / goblin_red_small.png / goblin-red-512x512.tga
• AFTER: character_goblin_red_512.ktx2
• Why: category-first (character), variant kept (red), integer power-of-two size

(512), 3D destination → .ktx2.

Texture, no variant → literal base, 3D prop, 1024px

• BEFORE: crate_1024.png (variant slot dropped, wrong ext)
• AFTER: prop_crate_base_1024.ktx2
• Why: missing variant becomes the literal base; 3D → .ktx2.

Texture, UI element, 1024px

• BEFORE: closeButton_pressed.png / ui_close_button_large.png
• AFTER: ui_closebutton_pressed_1024.png
• Why: category ui, single-token name, real variant pressed, integer size, UI → .png.

Texture, fx in a 2D UI overlay, 128px

• BEFORE: explosion_spritesheet.png (no category, no size)
• AFTER: fx_explosion_base_128.png
• Why: category fx, base filler since "sprite-sheet" is not a visual variant, UI

overlay → .png.

Texture, environment, 2D menu backdrop, 4096px, night

• BEFORE: forest_night_bg.jpg
• AFTER: environment_forest_night_4096.png
• Why: bg→environment, variant night, flat menu/UI use → .png, not .jpg.

Audio, sfx in combat

• BEFORE: SwordSwing.wav / sword_swing_sfx.mp3
• AFTER: sfx_combat_sword_swing.ogg
• Why: category-first sfx, context SECOND combat, no size token, .ogg.

Audio, looping menu music

• BEFORE: title_theme.mp3 / music_title.wav
• AFTER: music_menu_title_loop.ogg
• Why: music, context menu, loop as the variant, .ogg.

Audio, voice line, town menu

• BEFORE: merchant_greeting.wav
• AFTER: voice_menu_merchant_greeting.ogg

Audio, ambient world loop

• BEFORE: wind_ambience.ogg (missing category/context order)
• AFTER: ambient_world_wind_loop.ogg

Data file

• BEFORE: EnemyStats.yaml / enemy-stats.json
• AFTER: enemy_stats.json

Edge cases & exceptions

• No variant on a texture → use the literal word base (ui_healthbar_base_256.png).

Do not drop the slot; the four-token shape is fixed.

• No variant on audio → simply omit it (sfx_ui_click.ogg). Audio has no base

filler; the minimum is category_context_name.

• "fx" / "vfx" / "particle" all map to the texture category fx (when it is a

texture). A particle texture used on a 3D world model is still .ktx2; one used as a 2D UI overlay is .png. Destination decides the extension, not the word "fx".

• A tile is its own category, separate from environment. Ground/terrain tiles use

tile; large background/level art uses environment.

• Format is by destination, not by what was authored. A texture exported as a PNG but

destined for a 3D model still ships as .ktx2; the filename reflects the destination.

• Multi-word subjects collapse into one lowercase name token: "close button" →

closebutton, "health bar" → healthbar. Don't introduce an extra underscore that would shift the token positions.

• Albedo / normal / diffuse maps are still just textures of their model's category

(e.g. a dragon boss albedo → character_dragon_base_2048.ktx2); the map type is not a token in this grammar.

Do / Don't

• DO put category first, always. DON'T lead with the subject name.
• DO use the canonical category vocabulary. DON'T invent char, enemy, bg, vfx,

terrain, icon.

• DO use an integer power-of-two size token for textures. DON'T use small/large/hi

or 512x512.

• DO insert the literal base when a texture has no variant. DON'T drop the variant slot.
• DO pick the extension by destination: UI→.png, 3D→.ktx2, audio→.ogg. DON'T keep

the source format (.psd, .wav, .mp3, .tga, .jpg).

• DO put audio context second with NO size token. DON'T copy the texture shape onto audio.
• DO use lowercase + underscores only. DON'T use spaces, hyphens, camelCase, or PascalCase.

Common mistakes (the bare model's wrong defaults)

1. CamelCase / PascalCase descriptive names (GoblinRed.png) instead of token grammar.
2. Subject-first ordering (goblin_character_...) instead of category-first.
3. Word sizes (_small, _large, _hi) instead of the integer power-of-two.
4. Dropping the base variant slot on textures with no variant.
5. Keeping the authoring/source extension (.psd, .tga, .jpg, .wav, .mp3) instead

of the destination format.

1. Using .png for a 3D texture (should be .ktx2) or .ktx2 for a UI texture (should

be .png).

1. Putting a size token on audio, or audio context in the wrong slot.
2. Hyphens or spaces as separators.

Quick checklist

• ] Category token first, from the fixed vocabulary?
• ] Texture: category_name_variant_size.ext, integer power-of-two size, base if no variant?
• ] Audio: category_context_name[_variant].ogg, context second, no size token?
• ] Extension by destination — UI .png, 3D .ktx2, audio .ogg, data .json?
• ] All lowercase, underscores only, no source-format extension?