Fivem Assets

FiveM Asset Data — trunk

This file is the trunk: the rules that hold in every branch, and the map of the tree. Details are in the branch and leaf files; from here you are only routed. A fact is written once, in the widest place where it holds.

TREE — trunk / branch / leaf

• Trunk — this file + trunk/: GTA V's own rules (data model, file types, hash, coordinates, texture/DDS, streaming, resource format, client/server), our working discipline, tool pitfalls, verification ladder, flags, bone tags. Criterion: an item that does not hold in every branch and every leaf does not go in the trunk.
• Branch — branches/<branch>/_branch.md: the category's broad rules + the leaf list.
• Leaf — branches/<branch>/<leaf>.md: only what is specific to that task. A leaf is defined by the thing wanted; "road destruction / bridge destruction / explosion" is one leaf.

Use: when a topic comes up, open the branch first (_branch.md), then a single leaf. Do not scan every file; keyword → branch → leaf.

The full keyword list is at the top of every _branch.md.

⛔ Route by CLASS, not by KEYWORD

Keywords are an accelerator, not a dictionary. The set of words is infinite (roller shutter · sign · fountain), the set of classes is closed: 6 branches.

1. If a keyword matches → the branch is known, open it.
2. If none matches, do not stop: look at the What belongs here: definition at the top of branches/<branch>/_branch.md and classify the sentence. "Make the roller shutter open" → a roller shutter is a door object → /prop.
3. Adding a keyword to the list is the exception: only for a term that comes up often and cannot be inferred from the definition. Do not add every word — the list bloats.

If the class definition does not settle it either → ask.

TRUNK FILES

⛔ IF DATA IS MISSING, DO NOT GUESS

Every answer rests on the data/ layers. If a layer is missing, the query returns exit 2; at that point the only thing to do is stop:

python "${CLAUDE_PLUGIN_ROOT}/scripts/setup.py" --plan   # shows the state, writes nothing
python "${CLAUDE_PLUGIN_ROOT}/scripts/setup.py"          # installs the missing layers (/asset-setup)

Exit codes: 0 found · 1 the query ran, the name is not in the authority · 2 the layer is not installed — says nothing about the result · 3 internal error, not "absent". Confusing 2 with 1 means reading a "0 results" that came from a missing layer as "does not exist in the game".

CORE RULE — data first, code second

Before writing code about an object/prop/door/animation, look at that asset's data. Real case: four natives were tried in turn on the Fleeca teller door v_ilev_gb_teldr; the answer was in one line of the ytyp — specialAttribute = 0, i.e. not a door. assetdb.py door v_ilev_gb_teldr would have said so from the start.

WORKING DISCIPLINE — in every branch, with every tool

1. Measurement > guess. A number (tag, flag, duration, lodDist, fxName) is not guessed, it is queried. A number from an external tool is a claim; without a [verified] label, measure it first (sources/external-tools.md).
2. A tool not showing something does not mean that thing is absent. CodeWalker cannot write .yed bytecode, PowerShell returns $null.Length=0 on a property that does not exist, Sollumz imports a binary "in 0.0 seconds" — all three were taken for "absent".
3. A tool raising no error does not mean the work is right. Nearly all the bugs in this repository are silent: the file is created, it says "success", nothing happens in the game. All of them are in trunk/tool-pitfalls.md.
4. A screenshot is not a measurement. Before saying something is broken, read: the pixel, the file, the read-back. (In one round the screenshot was looked at three times and the wrong diagnosis was made.)
5. "The object was created, the numbers look reasonable" does not mean it works. Numbers and screen are both needed; working at one synthetic point is not enough, a fix is not delivered before it has been tried in the user's real situation.
6. Read back what you wrote. File size is not a validity criterion (RSC7 zlib); the only criterion is reading back. If a script crashes midway, the next Write does not run — cat/grep before saying "written". After a copy, compare size/hash.
7. The order of operations is part of the measurement. Do not look at a single number but at two independent numbers agreeing (reached vs target). A number can be right while when it was measured is wrong.
8. The reference itself can be broken. Two independent decoders can share the same mistake; do not say "I measured" without comparing against vanilla.
9. One variable at a time. If something does not work, split the chain into parts, set up A/B; do not ask for a test before the chain is complete; do not jump from symptom to hypothesis and try things one by one.
10. A grid can ask the wrong question — "100/100 points filled" does not mean the place that was not sampled does not exist. The measurement can be right and the question wrong.
11. A tool's constant is tuned to its own scale — do not copy the constant, copy what it is normalised against (shadow bias was right for a 0.15 m prop, in a 660 m scene it shadowed 72% of the ground).
12. Before guessing a field's meaning from its distribution, look at how the tool names that field (bl_rna.properties[...].enum_items). All three guesses for Flashiness were wrong; Sollumz had a named enum.
13. Do not write 0 into an Unknown* field — look at its distribution, take the most common value.
14. Pick a recipe and apply it to the end; do NOT HYBRIDISE two recipes. A hybrid of two paths that are each correct on their own never worked. If the recipe is unclear, clarify it with AskUserQuestion.

ENGINE INVARIANTS — whatever the branch

• Asset changed → leave the server and reconnect. The stream is cached, a restart is not enough; skip it and you test a stale asset. Remind the user before asking for a test.
• A broken stream asset silently drops the whole resource — no command registers on the client, no error. If commands suddenly vanished, look at stream/, not at the Lua. If a resource is in two folders, one is ignored → server log.
• A magic number is not copied, it is decoded: assetdb.py flags <number> [--entity]. 1572872 = LOD in Parented YMAP + Cast Static/Dynamic → for a ymap; 18350080 = Dont Render In Reflections + two shadow bits → for an MLO entity. Mixing them up silently deletes the object. → trunk/flags.md
• Bone: is the name fixed or the tag? The script side (GetEntityBoneIndexByName) uses the name, the file side (.ycd/.yed/specialAttribute) uses the tag. GetPedBoneIndex takes a TAG. → trunk/bone-tags.md
• The bbox must cover the whole animation — in two separate places: the .ydr's own BoundingBox/Sphere and the ytyp archetype box. If one is fixed and the other stays at rest, the object flickers and disappears at distance.
• physicsDictionary never 0 — the model is visible and you walk through it.
• An object spawned by script is not a map object; props are not placed inside an MLO with a ymap; SetEntityCollision(false) is unreliable on a map object.
• CreateObject places at the collision-bound BASE, CreateObjectNoOffset at the ORIGIN — a stale bound lifts the object into the air, the bound is regenerated from the visual. An attached object is positioned from its origin; adding a bone to a prop gives no alignment, the alignment is baked into the model.
• Collision is not chased with script — SetEntityCollision / Freeze / SetEntityHeading / DoorSystemSetOpenRatio break the animation chain.
• Custom ped skeletons are forbidden; the engine accepts only its own skeleton.
• DUI/NUI is client-side — password/code/price comparison happens on the server.
• Texture: DDS required, both edges a power of two, DXT + mip chain. PNG is skipped silently, a texture that is not a power of two flickers, DXT1 carries no alpha (holes close). → trunk/gta-fundamentals.md §5
• Archetype (what) ≠ entity (where) ≠ drawable (how it looks) — three separate files; fixing the ytyp affects every place that uses that model. → trunk/gta-fundamentals.md §1
• Clip name = prop model name (detecting an item animation). Duration is not guessed, it is taken from the index.

QUERY TABLE — the user gives no command, you look

The moment the topic comes up, before writing code:

All of them are python "${CLAUDE_PLUGIN_ROOT}/scripts/assetdb.py" <subcommand>. Summarise the result in a sentence or two, then move to the code. The index is built from the vanilla RPFs + the server's own ytyps; rebuilding it is /asset-build.

VERIFICATION LADDER — the game is the last resort

Do not carry a bug that one step can catch down to a lower step. Full recipe: trunk/verification-ladder.md.

WHEN AN IMAGE IS NEEDED — do not generate it, suggest it and give a prompt

Screen background, icon, logo, texture: do not invent a placeholder. Describe the idea (what, where, from what distance, tone) → give the user a ready prompt with the aspect ratio and resolution → until the image arrives, build the layout in code and leave an empty box of the right size. An invented image does not fit the tone; the work is done twice.

WHEN IT IS NOT ENOUGH

Fragment internals → inspect the .yft · animation duration/events → .ycd · internal layout of the server's own MLOs → /asset-build -ExtraFolders brings the archetypes, the internal entity expansion depends on vanilla ymaps. In these cases do not guess; say what to look at in CodeWalker or ask for an in-game measurement.