terra-llm/Assets/LLM/source/Documentation/4_Query_Strategy_Guide.md

LLM Query Strategy for Unity Project Data

1. Core Principle: Top-Down Analysis

The project data is split into three levels of detail (High, Mid, Low) to enable efficient querying. Always start with the highest, most abstract level of data and only "drill down" to a more detailed level when the query requires it. This prevents unnecessary processing of large, granular files.

The workflow is always: High -> Mid -> Low. Never start with the Low-level data unless you have a very specific fileID you need to look up.

2. The Triage Process: Which Zip to Use?

When you receive a user query, use the following decision process to select the correct data source.

Step 1: Is it a Project-Wide Question?

First, check if the question is about the project's global configuration, dependencies, or a general summary.

• Keywords: "settings", "package", "version", "scenes in build", "tags", "layers", "render pipeline".
• Action: Use HighLevel.zip.
• Example Queries:
  • "What is the name of the game?" -> Read manifest.json.
  • "Which version of the Universal Render Pipeline is installed?" -> Read packages.json.
  • "Is the 'PostProcessing' layer defined?" -> Read manifest.json.

Step 2: Is it about Structure, Hierarchy, or Asset Location?

If the question is about the arrangement of objects within a scene/prefab, what components an object has, or where assets are, the Mid-level data is the correct source.

• Keywords: "hierarchy", "list objects", "what components", "find all prefabs with", "children of", "location of".
• Action: Use MidLevel.zip.
• Example Queries:
  • "Show me the hierarchy of SampleScene.unity." -> Read Assets/Scenes/SampleScene.json and format the nested structure.
  • "What components are on the 'Player' GameObject?" -> Find the 'Player' object in the relevant scene/prefab JSON and list its components.
  • "Find all objects with a 'Rigidbody' component." -> Scan all scene/prefab JSON files, check the components list for each object.
  • "Where is the PlayerController.cs script?" -> Find the script's GUID in the components list of an object, then look up that GUID in GuidMappers/scripts.json to get the file path.

Step 3: Is it about a Specific, Raw Property Value?

Only proceed to this step if the user asks for a specific detail that is not present in the Mid-level hierarchy view. You should ideally already have the fileID of the target object from a previous Mid-level query.

• Keywords: "exact position", "specific value", "rotation", "scale", "property of", "what is the speed".
• Action: Use LowLevel.zip.
• Example Queries:
  • "What are the exact local position coordinates of the 'Gun' object in the Player prefab?"
    1. Mid-Level: First, open Assets/CustomGame/Prefabs/Player.json. Find the "Gun" object in the hierarchy to get its fileID (e.g., 101112).
    2. Low-Level: Now, navigate to the exploded directory: Assets/CustomGame/Prefabs/Player.prefab/. Find the Transform component associated with the "Gun" GameObject (you may need to open 101112.json to find its component fileIDs). Open the Transform's JSON file (e.g., 1011120.json) and read the value of the m_LocalPosition key.
  • "What is the 'movementSpeed' value in the 'PlayerController' script on the Player object?"
    1. Mid-Level: Find the Player object in the scene, get the GUID for its controller script.
    2. Low-Level: Open the corresponding .../{player_fileID}.json file. Find the MonoBehaviour component that matches the script GUID. Look at its properties to find the movementSpeed value.

4. De-Tokenization Reminder

For all JSON files, always check for tokenization first. If the file contains a key_mapper, you must de-tokenize the data payload before attempting to process it according to the schemas and strategies outlined above.