### Initialize Tutorial System

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Initializes the interactive tutorial system, loading the necessary tutorial map and preparing for guided user experiences.

```cpp
void tutorial_init();
```

--------------------------------

### Track Initialization Events with timestampactivity

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10

The `timestampactivity` function is used to log various initialization steps during application startup. It takes an integer (likely a type or level) and a string message. Examples show tracking 'initial setup', 'splash screen', 'authentication check', and directory changes.

```cpp
timestampactivity(0, "initial setup");
timestampactivity(0, "splash screen");
timestampactivity(0, "authentication check");
timestampactivity(0, pOldDir.Get());
```

--------------------------------

### Highlight UI Elements in Tutorial

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Visually guides the user by drawing highlights, such as red outlines or arrows, around relevant UI elements during tutorials.

```cpp
void tutorial_highlight_ui();
```

--------------------------------

### Setup Character Controller Physics

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Performs specialized physics setup for character controllers. This involves creating a character capsule shape, initializing `btKinematicCharacterController`, and integrating it with the AI pathfinding system for animation and movement. This function ensures characters behave correctly within the physics world.

```C++
physics_setupcharacter()
```

--------------------------------

### Behavior File (.byc) Instruction Example

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/6

An example of a compiled behavior file (.byc) instruction block, showing format version, instruction count, state count, data size, state names, instruction ID, state index, condition type, action type, and next/alternative instructions.

```byc
42          -- Format version
102         -- Instruction count
9           -- State count
299         -- Data size
Initial     -- State names
1
Idle
1
Attacking
...
---
2186        -- Instruction ID
1           -- State index
11          -- Condition type (g_masterinterpreter_cond_always)


24          -- Action type (g_masterinterpreter_act_settargetenemy)


2           -- Next instruction
0           -- Alt instruction

```

--------------------------------

### Prompt Display System Example Implementation (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7-behavior-script-library

Shows how to implement different prompt display modes based on a configuration property. It conditionally calls either `PromptLocal` for world-space prompts or `Prompt` for HUD prompts, using text defined in the object's properties. Dependencies include global prompt functions and object-specific properties like `prompt_display` and `prompt_text`.

```lua
if searchobject[e].prompt_display == 1 then 
    PromptLocal(e, searchobject[e].prompt_text)
end
if searchobject[e].prompt_display == 2 then 
    Prompt(searchobject[e].prompt_text)
end
```

--------------------------------

### TSV File Format for Collection Data (Example)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Illustrates the Tab-Separated Value (TSV) file format used by the collection system for storing item and quest data. Examples show the structure for 'items.tsv' and 'quests.tsv', including headers and data rows.

```text
title	profile	image	description	cost	value	container	ingredients	style
Pistol	weapon\pistol.fpe	weapon\pistol.png	A basic handgun	100	50	shop		weapon
Medkit	items\health.fpe	items\health.png	Restores health	50	25	shop		consumable

name	description	objective	reward
Find the Key	Locate the key in the dungeon	Find key item	Gold:100
```

--------------------------------

### BYC File Format Example (Conceptual)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7

Illustrates the conceptual structure of a Behavior Compiled (.byc) file, which encodes state machines for AI. These files define states, conditions, and actions in a compact, binary format, enabling data-driven behavior modification.

```plaintext
-- Example: melee_attack.byc defines 9 states (Initial, Idle, Attacking, Damage, Run Away, Recover, Ground Work, Block and Counter, Get Close) with 299 total instructions.
```

--------------------------------

### LUA Script Initialization in C++

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/4

Handles the initial loading and setup of LUA scripts for entities. It loads the script file, constructs the initialization function name, calls the LUA init function, and marks the script as initialized to prevent re-execution.

```cpp
lua_loop()
lua.firsttime == 0
lua_loadscriptin()
t.entityelement[e].eleprof.aimain_s
init_name(e)
lua_initscript()
LoadLua()
t.entityelement[e].lua.firsttime = 1
```

--------------------------------

### Standard Lua Script Lifecycle and Structure Example (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7-behavior-script-library

Demonstrates the typical structure and lifecycle functions (properties, init, main) for a standard Lua script in the game engine. It includes entity-specific property storage and basic behavior logic for a weapon pickup. This script relies on the 'module_misclib' for utility functions.

```lua
-- DESCRIPTION: Weapon pickup behavior
-- DESCRIPTION: [PICKUP_RANGE=75(1,200)]
-- DESCRIPTION: [@PICKUP_STYLE=2(1=Ranged, 2=Accurate)]

local module_misclib = require "scriptbank\module_misclib"
g_tEnt = {}

local weapon = {}
local pickup_range = {}
local pickup_style = {}
local status = {}

function weapon_properties(e, pickup_range, pickup_style, ...)
    weapon[e].pickup_range = pickup_range or 75
    weapon[e].pickup_style = pickup_style
end

function weapon_init(e)
    weapon[e] = {}
    weapon[e].pickup_range = 75
    weapon[e].pickup_style = 1
    status[e] = "init"
end

function weapon_main(e)
    if status[e] == "init" then
        -- First-frame initialization
        status[e] = "running"
    end
    
    local PlayerDist = GetPlayerDistance(e)
    if PlayerDist < weapon[e].pickup_range then
        module_misclib.pinpoint(e, weapon[e].pickup_range, 0, 0)
        if g_tEnt == e and g_KeyPressE == 1 then
            AddPlayerWeapon(e)
            Destroy(e)
        end
    end
end

```

--------------------------------

### Thread-Safe Image Preloading API

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/9

Provides the API for a thread-safe image preloading system designed to improve startup performance. It includes functions to initialize, add files to, start, wait for, check progress of, and reset the preloading process.

```cpp
// Initialize preload batch
void image_preload_files_start();

// Add texture to batch
void image_preload_files_add(LPSTR pFilename, int iMipMaps);

// Start background loading thread
void image_preload_files_finish();

// Block until loading completes
void image_preload_files_wait();

// Check if still loading
bool image_preload_files_in_progress();

// Clear preloaded data
void image_preload_files_reset();
```

--------------------------------

### Crash Handler Initialization and Setup

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10

Registers the crash handler early in the application startup process. It sets up necessary global variables and links the Wicked Engine's debug output to the crash context. The system can be disabled via a flag in SETUP.INI.

```cpp
// GameGuru Core/Guru-WickedMAX/CrashLogger.cpp
// Registers CrashHandler() as unhandled exception filter
void InitCrashHandler() { /* ... */ }

// GameGuru Core/Guru-WickedMAX/CrashLogger.cpp
// Stores build timestamp for dump/symbol matching
DWORD64 g_pCrashVersionINIValue;

// GameGuru Core/Guru-WickedMAX/CrashLogger.h
// Returns pointer to g_pDebugExtraInfo buffer (10240 bytes)
char* GetCrashHandlerDebugLogRef();

// GameGuru Core/Guru-WickedMAX/main.cpp
// Links Wicked Engine debug output to crash context
void SetSpecialGGDebugLog();

// GameGuru Core/Guru-WickedMAX/main.cpp
// Flag to disable crash log system, can be set via SETUP.INI
extern int g_iDisableCrashLogSystem;

```

--------------------------------

### Welcome System and Tutorials

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Provides an overview of the welcome system, its architecture, page flow, and integration with tutorials and onboarding.

```APIDOC
## Welcome System & Tutorials

### Description
The welcome system is designed for user onboarding, serial code validation, and providing access to interactive tutorials. It integrates with the editor's ImGui interface and is primarily implemented in M-WelcomeSystem.cpp.

### Welcome Page Flow:
- **Trigger**: Displays on the first launch or when manually triggered.
- **`welcome_init()`**: Initializes the welcome system and loads user preferences.
- **`welcome_loop()`**: Updates the welcome page UI and handles user interactions.
- **`welcome_show()`**: Forces the welcome page to display, bypassing preferences.
- **`welcome_hide()`**: Dismisses the welcome page and saves the 'don't show again' preference.

### Welcome Page Contents:
- Product information and version details.
- Serial code entry field (for non-platform authenticated builds).
- Quick-start guide covering basic controls.
- Tutorial selection buttons.
- Links to documentation and community resources.
- A checkbox to disable the welcome page on subsequent startups.
```

--------------------------------

### GameGuru MAX Build Steps

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/1

This section details the manual steps required to build the GameGuru MAX project using Visual Studio 2022. It covers opening the solution, selecting the correct configuration, setting the startup project, and performing the rebuild process. The output executable is located at $(GG_MAX_BUILD_PATH)\Max\GameGuruMAX.exe.

```text
1. **Open Project** : Navigate to `GameGuru Core\GameGuruWickedMAX.sln` and open in Visual Studio 2022
2. **Select Configuration** : Change Solution Configuration from "Debug" to desired target (typically "Release" for development)
3. **Set Startup Project** : Right-click "Wicked-MAX" project → Set as Startup Project
4. **Rebuild** : Right-click "Wicked-MAX" → Rebuild
5. **Verify Output** : Check `$(GG_MAX_BUILD_PATH)\Max\GameGuruMAX.exe` exists
```

--------------------------------

### Get Available System Memory

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Retrieves the amount of available system RAM in bytes.

```cpp
long SMEMAvailable();
```

--------------------------------

### Display Tutorial Messages

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Presents instructional text and tooltips to the user, explaining current objectives and providing contextual help within the tutorial system.

```cpp
void tutorial_show_message();
```

--------------------------------

### Advance Tutorial Step

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Progression mechanism for the tutorial system, moving the user to the next step once the current conditions are met.

```cpp
void tutorial_advance();
```

--------------------------------

### Get Total VRAM Usage

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Calculates and returns the total video memory currently being utilized by all resources.

```cpp
long GetTotalVramUsage();
```

--------------------------------

### Get Available Video Memory

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Queries and returns the amount of available dedicated video memory (VRAM) using DXGI.

```cpp
long DMEMAvailable();
```

--------------------------------

### Update Tutorial State

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Manages the ongoing state of the tutorial, processing user actions and advancing the tutorial steps as conditions are met.

```cpp
void tutorial_loop();
```

--------------------------------

### Download and Integration Workflow

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Outlines the step-by-step process for downloading Workshop items, from user subscription to file extraction and system refresh.

```APIDOC
## Download and Integration Workflow

### Description
This workflow details the process of downloading and integrating Workshop items into the system, initiated by a user's subscription action.

### Download Process Steps:
1.  **User Subscription**: User clicks the subscribe button in the Marketplace window.
2.  **API Call**: The Workshop system calls `ISteamUGC::SubscribeItem()`.
3.  **Background Download**: Steam downloads the files in the background.
4.  **Download Completion Callback**: A callback is triggered upon successful download.
5.  **Retrieve Install Path**: The system retrieves the installation path using `ISteamUGC::GetItemInstallInfo()`.
6.  **Decryption**: Workshop files are decrypted if they are encrypted.
7.  **Extraction**: Files are extracted to the appropriate `Community` folder (e.g., `Files/{type}/Community/`).
8.  **System Refresh**: Entity banks, script banks, etc., are refreshed to include the newly added content.
```

--------------------------------

### Get Entity Position via Lua

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Retrieves the X, Y, or Z coordinate of an entity's position using the Lua interface. These functions allow scripts to query the current location of entities in the game world.

```Lua
GetEntityPositionX(e)
GetEntityPositionY(e)
GetEntityPositionZ(e)
```

--------------------------------

### Get Close and Speak Behavior Script

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7

Handles dialog interactions for AI characters. It defines the distance at which the AI should stop to speak and allows configuration of the sound file to play and whether to resume patrol after speaking.

```lua
-- Configuration:
-- range: Distance to stop and speak
-- speech1: Sound file to play
-- followpathafter: Resume patrol after speaking
```

--------------------------------

### Collection System Initialization and Persistence Functions (C++)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Provides an overview of functions related to initializing, loading, saving, and managing the collection system. This includes clearing lists, loading from TSV files, saving collections, and refreshing item data from game entities.

```cpp
// Function: init_rpg_system()
// Purpose: Clears all collection lists

// Function: load_rpg_system(name)
// Purpose: Loads items and quests from TSV files

// Function: save_rpg_system(name, bIncludeELEFile)
// Purpose: Saves collections to TSV files, optionally saves ELE data

// Function: refresh_collection_from_entities(bLoadingLevel)
// Purpose: Scans entities and auto-creates weapon items

// Function: refresh_rpg_parents_of_items()
// Purpose: Updates parent-child relationships

// Function: find_rpg_collectionindex(name)
// Purpose: Finds item index by name
```

--------------------------------

### Check Tutorial Step Completion

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10-build-system-and-platform-integration

Verifies if the user has successfully completed the current step in the tutorial by checking for specific actions or conditions.

```cpp
bool tutorial_check_condition();
```

--------------------------------

### Raycast Through Scene via Lua

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Performs a raycast through the entire scene from a starting point (x1, y1, z1) to an ending point (x2, y2, z2). It can exclude a specific object (`objExclude`) from the intersection test.

```Lua
IntersectAll(x1, y1, z1, x2, y2, z2, objExclude)
```

--------------------------------

### Get NPC Allegiance (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7

This Lua code snippet shows how to retrieve the allegiance value of an NPC entity. The allegiance determines the NPC's behavior towards the player, with values ranging from 0 (Enemy) to 2 (Neutral).

```lua
allegiance[e] = GetEntityAllegiance(e) -- (0-enemy, 1-ally, 2-neutral)
```

--------------------------------

### Physics System Initialization Parameters (C++)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Outlines the default parameters and initialization steps for the physics system. This includes setting player control parameters like jump height, gravity, and acceleration, as well as loading material sound mappings.

```cpp
// Function: physics_inittweakables()
// Sets default player physics parameters:
// regenrate, regenspeed, regendelay - Health regeneration
// jumpmax_f (215.0) - Jump height
// gravity_f (900.0) - Gravity strength
// fallspeed_f (5000.0) - Maximum fall speed
// climbangle_f (66.0) - Climbable slope angle
// accel_f (25.0) - Movement acceleration

// Function: physics_init()
// Initializes the physics system:
// Loads material sound mapping from matsounds.txt.
// Maps terrain material IDs to sound material indices.
// Initializes player control state and character controller parameters.
```

--------------------------------

### Raycast Static Objects Only via Lua

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Performs a raycast against static objects only in the scene, from a starting point (x1, y1, z1) to an ending point (x2, y2, z2). It can exclude a specific object (`objExclude`) from the intersection test.

```Lua
IntersectStatic(x1, y1, z1, x2, y2, z2, objExclude)
```

--------------------------------

### Initialize Newly Spawned Entities (C++)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/4

Initializes entities that have been dynamically spawned during gameplay. This process involves adding them to the activation list and calling their LUA initialization functions.

```cpp
entity_bringnewentitiestolife();
// LUA init functions are called on the first frame after this.
```

--------------------------------

### Caching Animation Frames for NPC Control

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7

This code snippet demonstrates how the NPC control system caches animation start and finish frames to optimize performance by avoiding repeated lookups. It initializes and adjusts frame counts for different attack animations.

```lua
if setframes[e] == 0 then
    staanim1[e], finanim1[e] = GetEntityAnimationStartFinish(e, npc_control[e].attack1_animation)
    staanim2[e], finanim2[e] = GetEntityAnimationStartFinish(e, npc_control[e].attack2_animation)
    staanim3[e], finanim3[e] = GetEntityAnimationStartFinish(e, npc_control[e].attack3_animation)
    frameadjust1[e] = staanim1[e] + npc_control[e].attack1_hitframe
    frameadjust2[e] = staanim2[e] + npc_control[e].attack2_hitframe
    frameadjust3[e] = staanim3[e] + npc_control[e].attack3_hitframe
    setframes[e] = 1
end
```

--------------------------------

### DarkLUA Firemode Settings Functions

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/8-gameplay-systems

Provides Lua access to get and set specific firemode parameters for weapons, such as damage, accuracy, reload quantity, range, and fire rate. These functions allow fine-tuning of weapon behavior based on different firing modes.

```lua
-- Damage
GetWeaponDamage(gunid, firemode) / SetWeaponDamage(gunid, firemode, value)

-- Accuracy
GetWeaponAccuracy(gunid, firemode) / SetWeaponAccuracy(gunid, firemode, value)

-- Reload Quantity
GetWeaponReloadQuantity(gunid, firemode) / SetWeaponReloadQuantity(gunid, firemode, value)

-- Fire Iterations
GetWeaponFireIterations(gunid, firemode) / SetWeaponFireIterations(gunid, firemode, value)

-- Range
GetWeaponRange(gunid, firemode) / SetWeaponRange(gunid, firemode, value)

-- Dropoff
GetWeaponDropoff(gunid, firemode) / SetWeaponDropoff(gunid, firemode, value)

-- Spot Lighting
GetWeaponSpotLighting(gunid, firemode) / SetWeaponSpotLighting(gunid, firemode, value)

-- Fire Rate
GetWeaponFireRate(gunid, firemode) / SetWeaponFireRate(gunid, firemode, value)

-- Clip Capacity
GetWeaponClipCapacity(gunid, firemode) / SetWeaponClipCapacity(gunid, firemode, value)
```

--------------------------------

### Steam Offline Mode Data Structure

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/1

Illustrates the data structure and calculation for the `installsteam.dat` file used in GameGuru MAX's offline authentication. This includes the encoded date value and a checksum, both calculated using specific formulas to ensure data integrity and track the validity period for offline play.

```cpp
// Example of data encoding for installsteam.dat
// Assuming year, month, day are available
int encodedDate = (year * 380) + (month * 31) + day;
int checksum = (year * 1165) + (month * 412) + (dayTrick * 9);

// The file 'installsteam.dat' would store these values.
// It is valid for 30 days from the last online authentication.
```

--------------------------------

### Limit Expensive Queries with Timers in Lua

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/6

This Lua example demonstrates limiting expensive queries, such as line-of-sight checks, by using timers. The `GetEntityPlayerVisibility` function is only called when needed (e.g., during 'pursuing' state) and at a set interval, optimizing performance.

```lua
-- Check line-of-sight only when needed
if state[e] == "pursuing" and g_Time > los_check_time[e] then
    GetEntityPlayerVisibility(e)  -- Expensive raycast
    los_check_time[e] = g_Time + 250
end
```

--------------------------------

### Log Error Conditions with timestampactivity

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/10

The `timestampactivity` function is utilized to log various error conditions encountered by the application. Examples include logging error strings, specific success messages like 'GameGuru MAX Steam version owned!', and initialization failures such as '[EOS SDK] Init Failed!'.

```cpp
timestampactivity(0, pErrorStr);
timestampactivity(0, "GameGuru MAX Steam version owned!");
timestampactivity(0, "[EOS SDK] Init Failed!");
```

--------------------------------

### Sound System Integration and Playback (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7-behavior-script-library

Details the standardized sound slot system for playing sounds within behaviors. It covers one-shot playback, looping, stopping, setting active sounds, adjusting volume, and utilizing 3D positioning for spatial audio. Global sound playback for background music is also supported.

```lua
-- DESCRIPTION: <Sound0> for primary sound
-- DESCRIPTION: <Sound1> for secondary sound
-- DESCRIPTION: <Sound2> for additional sound

-- Playback functions
PlaySound(e, soundslot)        -- One-shot playback
LoopSound(e, soundslot)        -- Continuous loop
StopSound(e, soundslot)        -- Stop playback
SetSound(e, soundslot)         -- Set active sound
SetSoundVolume(volume)         -- Adjust volume 0-100

-- Global Sound System
PlayGlobalSound(g_Entity[e])
```

--------------------------------

### Configure Zone Trigger Properties in Lua

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7-behavior-script-library

This Lua code snippet shows how to configure properties for zone triggers, which are invisible volumes used for gameplay events. It includes settings for zone height and a flag to prevent spawning at the start. A sound effect can also be assigned for when the player enters the zone.

```lua
-- DESCRIPTION: [ZONEHEIGHT=100(1,500)]
-- DESCRIPTION: [SpawnAtStart!=1]
-- DESCRIPTION: <Sound0> for zone entry sound
```

--------------------------------

### Navigation Mesh Dynamic Obstacle Handling (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/7-behavior-script-library

Shows how to integrate with the navigation mesh system to create dynamic obstacles. The `HandleBlocker` function from the `navmeshlib` library manages obstacle states for AI pathfinding, ensuring NPCs avoid areas blocked by entities like doors.

```lua
-- Import navmesh library
local NAVMESH = require "scriptbank\navmeshlib"

-- Store original position for blocker placement
door.originalx = g_Entity[e]['x']
door.originaly = g_Entity[e]['y']
door.originalz = g_Entity[e]['z']

-- Update blocker state each frame
door.blocking = NAVMESH.HandleBlocker(
    e,                    -- Entity ID
    door.blocking,        -- Current blocking state
    door.originalx,       -- Original X position
    door.originaly,       -- Original Y position
    door.originalz        -- Original Z position
)
```

--------------------------------

### Example State Machine Logic in _main Function (Lua)

Source: https://deepwiki.com/Dark-Basic-Software-Limited/GameGuruMAX/6

This Lua code snippet demonstrates state machine logic within the `_main` function, specifically for an 'idle' state. It handles playing idle animations, looping them, and checking for state transitions based on time and entity properties like `npc_can_roam`.

```lua
if state[e] == "idle" then
    -- Play idle animations
    if idlemonce[e] == 0 then
        anim_var[e] = math.random(1,2)
        if anim_var[e] == 1 then 
            SetAnimationName(e,npc_control[e].idle1_animation) 
        end
        LoopAnimation(e)
        idlemonce[e] = 1
    end
    -- Check for state transitions
    if g_Time > idle_delay[e] then
        if idlestate_choice[e] == 5 and npc_control[e].npc_can_roam == 1 then
            state[e] = "roam"
        end
    end
end
```