terra-llm/Assets/LLM/source/Documentation/2_MidLevel_Data_Guide.md

LLM Guide: Mid-Level Project Data (MidLevel/)

1. Purpose

This data level provides a structural and relational view of the project's assets. It is designed for understanding the hierarchy of scenes and prefabs, and for locating assets within the project.

Use this data for questions like:

• "Draw the full visual hierarchy of SampleScene.unity."
• "List all GameObjects in the Player.prefab file."
• "What components are attached to the 'Main Camera' object?"
• "Find all prefabs that contain a script with the GUID a1b2c3d4...."
• "Where are all the material files located in the project?"

2. File Structure

The MidLevel folder will contain a replicated Assets/ directory and a GuidMappers/ directory.

MidLevel/
├── Assets/
│   ├── Scenes/
│   │   └── SampleScene.json  // This was originally SampleScene.unity
│   └── CustomGame/
│       └── Prefabs/
│           └── Player.json   // This was originally Player.prefab
└── GuidMappers/
    ├── materials.json
    ├── prefabs.json
    ├── scripts.json
    ├── scenes.json
    └── ... (other asset types)

3. Key Files & Schema

GuidMappers/*.json

These files map the unique GUID of an asset to its project-relative file path. This is essential for cross-referencing. For example, when you find a script GUID in a scene file, you can look it up in scripts.json to find the script's path.

Schema Example (scripts.json):

{
  "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6": "Assets/Scripts/PlayerController.cs",
  "f1e2d3c4b5a69876543210fedcba9876": "Assets/Scripts/Gun.cs"
}

Assets/**/*.json (Scene/Prefab Hierarchy)

Each .unity and .prefab file is converted into a single JSON file that describes its full visual hierarchy. The root of the JSON is a list of all top-level objects in that scene or prefab.

Schema Example (SampleScene.json):

[
  {
    "fileID": "14854",
    "m_Name": "Main Camera",
    "m_IsActive": 1,
    "m_TagString": "MainCamera",
    "m_Layer": 0,
    "components": [
      "Camera",
      "AudioListener",
      "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" // Script GUIDs are used for MonoBehaviours
    ],
    "children": []
  },
  {
    "fileID": "123456", // This is the fileID of the PrefabInstance
    "source_prefab_guid": "abcdef1234567890abcdef1234567890",
    "m_Name": "Explosion Effect",
    "m_IsActive": 1,
    "addedComponents": [], // Components added as an override in the scene
    "children": [
      {
        "fileID": "789012",
        "m_Name": "Smoke Trail",
        "m_IsActive": 1,
        "m_TagString": "Untagged",
        "m_Layer": 0,
        // This index preserves the object's order within the prefab's hierarchy
        "deep_sibling_index": "0-1", 
        "components": ["ParticleSystem"],
        "children": []
      }
    ]
  }
]

• fileID: The unique ID of the GameObject or PrefabInstance within the file.
• source_prefab_guid: Indicates that this node is an instance of a prefab.
• components / addedComponents: A list of components attached. For scripts, this is the script's GUID.
• children: A nested list of child objects, forming the tree structure.
• deep_sibling_index: Only present for scene objects parented under a prefab instance. It defines the object's precise location in the hierarchy for correct ordering.

4. Handling Shrunken / Tokenized Data

The JSON files in this folder may have been processed by json_reducer.py. You can identify this if the root object contains a key_mapper and a data key.

If the data is shrunken:

1. The file content will look like this: {"key_mapper":{"k0":"fileID",...},"data":[{"k0":"14854",...}]}
2. You MUST use the key_mapper object to de-tokenize the keys in the data object before you can interpret the schema.
3. The json_reducer also removes keys with empty values (e.g., an empty children array [] will be removed). If a key like children is missing from a de-tokenized object, you can assume its value was empty.

Once de-tokenized, the data will conform to the schemas described above.