Dagor Engine

https://gaijinentertainment.github.io/DagorEngine
Admin
Dagor Engine is an open-source, high-performance game engine by Gaijin with advanced graphics,...
Tokens:688,338
Snippets:4,594
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Sphinx and Dependencies

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/how_to_build_docs_locally

Installs Sphinx and its required packages using pip and a requirements file. This step is crucial for building the documentation.

```bash
pip install -r requirements.txt
```

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

### QDox Basic Module/Page Declaration

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

QDox comments must start with `///` or `/* qdox */`. Every file needs to declare a module or page using `///@module <name>` or `///@page <name>` to enable other documentation elements.

```qdox
///@module MyModule
///@page MyPage
```

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

### Exclusion Example with Override (.folder.blk)

Source: https://gaijinentertainment.github.io/DagorEngine/assets/collisions/static_object_collision

An example demonstrating how to exclude specific files from collision processing using the `@override-last` directive in conjunction with an included LOD file. This allows for fine-grained control over which assets are processed for collision.

```blk
include "#/develop/assets/_ri_collision_lod2.blk"
"@override-last"{ exclude:t="^(.*sign.*)\.lod02\.dag$"; }
```

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

### QDox C++ Code Commenting Example

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

This snippet demonstrates how to use QDox directives within C++ comments to generate documentation. It shows module definition, function documentation with return and parameter information, and constant definitions.

```cpp
void bind_webbrowser(SqModules* sq_modules_mgr)
{
  Sqrat::Table tbl(sq_modules_mgr->getVM());
  /* qdox @module browser

Opens embeded web browser. Requires native cef binary and its integration.

  */
  tbl
    .Func("can_use_embeded_browser", can_use_embedded_browser)
    ///@return b : Returns can browser be opened
    .Func("browser_go_back", go_back)
    .Func("browser_reload_page", reload)
    ///Will reload page
    .Func("browser_add_window_method", add_window_method)
    ///@param method c : add function
  ;

  using namespace webbrowser;

  CONST(BROWSER_EVENT_INITIALIZED);
  CONST(BROWSER_EVENT_DOCUMENT_READY);

  sq_modules_mgr->addNativeModule("browser", tbl);
}

```

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

### Setup Destruction Object Properties

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-tools/addons/blender/dag4blend/dag4blend

Assigns standard Object Properties for destruction setup to selected objects. It also creates bounding boxes and sets collider parameters. This function saves considerable setup time for destruction effects.

```text
animated_node:b=yes
physObj:b=yes
collidable:b=no
massType:t=none

materialName:t=[value from the 'material' field]
density:r=[value from the 'density' field]
massType:t=box
collType:t=box
```

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

### QDox Doc-Object: Tip

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

The `@tip` doc-object is used to provide helpful tips. Content is rendered until `tip@` is encountered or the comment ends. The example shows a simple tip.

```qdox
///@tip
/// Tip! Nice tip!
///tip@
```

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

### Autobuild Documentation with Sphinx-Autobuild

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

Starts a local development server that automatically rebuilds and reloads documentation in the browser upon detecting changes in source files or configurations. It watches the '_docs/source' directory and serves from '_docs/build/html' on port 8080.

```bash
@start python _docs/watch.py
@start sphinx-autobuild --port 8080 _docs/source _docs/build/html

```

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

### Start Rectangular Selection (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Initiates the drawing of a rectangular selection box within the viewport. Requires starting coordinates (mx, my) and a selection type.

```C++
virtual void startRectangularSelection(int mx, int my, int type) = 0;

```

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

### Name-Based Search Example with Override (.folder.blk)

Source: https://gaijinentertainment.github.io/DagorEngine/assets/collisions/static_object_collision

Illustrates using `@override-last` to modify the search pattern for collision processing. This example targets files containing specific names (e.g., 'pos_a', 'pos_b') within a particular LOD, enabling custom filtering.

```blk
include "#/develop/assets/_ri_collision_lod1.blk"
"@override-last"{ "@override:find":t="^(.*pos_a.*|.*pos_b.*|.*pos_c.*|.*sign.*)\.lod01\.dag$"; }
```

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

### Dagor Engine Node Placement Types Example

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/composit_blk

This example demonstrates how to define node placement types within a Dagor Engine configuration file. The `place_type:i=` parameter specifies the object's placement behavior relative to terrain or other objects.

```plaintext
node{
  name:t="fachwerk_horse_cart_a_cmp"
  tm:m=[[0.999018, 0, -0.0443057] [0, 1, 0] [0.0443057, 0, 0.999018] [-6.7688, 0.0028134, -1.22241]]
  place_type:i=1
}
node{
  name:t="haystack_i"
  tm:m=[[0.020657, 0, 0.999787] [0, 1, 0] [-0.999787, 0, 0.020657] [6.92909, 0, -1.47888]]
  place_type:i=3
}

```

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

### Ray Tracing Setup and Direct Tracing

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Methods for setting up collider parameters for ray tracing and performing a direct ray trace from a world point in a specified direction. These are fundamental for physics and collision detection.

```cpp
virtual void setupColliderParams(int mode, const BBox3 &area) = 0;
virtual bool traceRay(const Point3 &src, const Point3 &dir, real &dist, Point3 *out_norm = NULL, bool use_zero_plane = true) = 0;
```

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

### Install Sphinx and Dependencies for Documentation

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

Installs essential Python packages for documentation generation using Sphinx, including the Myst parser and Read the Docs theme. Ensure Python 3.10+ is installed and in your PATH.

```bash
pip install sphinx
pip install myst
pip install myst_parser
pip install sphinx_rtd_theme
pip install sphinx-autobuild

```

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

### Basic Export Parameters Example - Dagor Engine

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/folder_blk

Demonstrates setting texture pack and game resource pack names directly for a directory and its nested contents. These parameters define how assets are bundled and exported.

```dagor_config
ddsxTexPack:t="combat_suits.dxp.bin"
gameResPack:t="combat_suits.grp"

```

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

### Get Time in Milliseconds (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Returns the current time in milliseconds since the application started or an epoch.

```cpp
virtual int getTimeMsec() const = 0;

```

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

### Basic Configuration for *_animbnl.animtree.blk

Source: https://gaijinentertainment.github.io/DagorEngine/projects/dng/dng_non_human_char

Sets up the fundamental processing directives and root node for animation blending. 'export:b=yes' enables script processing, and 'root:t="fifo3"' defines the primary blending controller. 'defaultForeignAnim:b=yes' allows blending of external animations.

```blk
export:b=yes              // Process the script
root:t="fifo3"            // Root node for animation blending
defaultForeignAnim:b=yes  // Enables blending foreign animations
```

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

### Get Milliseconds Since Client Start - get_time_msec()

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/quirrel_gamelibs/dagor.time

Retrieves the number of milliseconds that have elapsed since the client application was started. This function is useful for measuring durations or performance within the application.

```squirrel
function get_time_msec():  -> integer
    
Returns the number of milliseconds that have passed since the client was started. 

Returns:
    
Milliseconds since client start 

Return type:
    
integer 

```

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

### Get Update Buffer Pitch (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/d3dAPI/ResUpdateBuffer

Returns the pitch of the update buffer, which is the number of bytes between the start of one row and the next. This is applicable for certain texture formats and layouts.

```cpp
size_t get_update_buffer_pitch(ResUpdateBuffer *rub)
```

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

### Build testGI Sample (Shell)

Source: https://gaijinentertainment.github.io/DagorEngine/getting-started/how_to_build

This command navigates to the 'testGI' sample's program directory and uses the 'jam' build tool to compile the sample. The resulting executable will be placed in the 'testGI/game' directory.

```shell
cd X:/develop/DagorEngine/samples/testGI/prog
jam
```

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

### QDox Doc-Object: Warning

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/qdox_user_guide

The `@warning` doc-object is used to highlight warnings. Content is rendered until `warning@` is encountered or the comment ends. The example shows a basic warning.

```qdox
///@warning
/// Warning!
///warning@
```

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

### Command Line Modification Example

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/config_and_settings_blk

Demonstrates how to modify settings via the command line, which is equivalent to adding entries to the .config.blk file. This allows for dynamic configuration changes without directly editing files.

```bash
game.exe -config:debug/watchdog:b=no
```

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

### Loft Geometry Visualization Setup

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/spline_blk

Instructions to enable visual display of loft geometry in the editor. This involves modifying material block files and spline block files, then applying changes.

```INI
render_landmesh_combined=0

```

```INI
render_landmesh_combined=1

```

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

### Identify Vehicle for Projectile Analysis

Source: https://gaijinentertainment.github.io/DagorEngine/assets/materials/physmats

This snippet shows an example of a vehicle identifier found in a mission file, used to trace projectile FX settings. It helps in pinpointing the specific vehicle to start the debugging process for projectile-related issues.

```plaintext
ussr_t64_b_1984
```

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

### Brush Manipulation Methods in C++

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Enables control over brush-related operations within the Dagor Engine. This includes starting and ending painting sessions, rendering the brush, and setting or getting the current brush object. These are crucial for texture painting and similar features.

```cpp
virtual void beginBrushPaint() = 0;
virtual void renderBrush() = 0;
virtual void setBrush(Brush *brush) = 0;
virtual Brush *getBrush() const = 0;
virtual void endBrushPaint() = 0;
virtual bool isBrushPainting() const = 0;
```

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

### Dynamic Export Parameters Example - Dagor Engine

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/folder_blk

Shows how to use special keywords like '*name_src' to dynamically set texture pack and game resource pack names based on the source directory name. This allows for flexible asset management.

```dagor_config
ddsxTexPack:t="*name_src"
gameResPack:t="*name_src"

```

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

### ResourceDescription Constructors for Various Resource Types

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/d3dAPI/Heap

Demonstrates the creation of a ResourceDescription object from different specific resource types like buffer, 2D texture, volume texture, array texture, cube texture, and array cube texture. These constructors facilitate type-safe initialization of a generic resource description.

```cpp
inline ResourceDescription(const BufferResourceDescription &buf) {}
inline ResourceDescription(const TextureResourceDescription &tex) {}
inline ResourceDescription(const VolTextureResourceDescription &tex) {}
inline ResourceDescription(const ArrayTextureResourceDescription &tex) {}
inline ResourceDescription(const CubeTextureResourceDescription &tex) {}
inline ResourceDescription(const ArrayCubeTextureResourceDescription &tex) {}
```

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

### Locate Weapon Preset File

Source: https://gaijinentertainment.github.io/DagorEngine/assets/materials/physmats

This example provides the directory path where weapon presets for vehicles are stored. Finding the correct weapon preset file is a crucial step in tracing projectile configurations.

```plaintext
<project_name>/develop/gameBase/gameData/units/tankModels/weaponPresets

ussr_t_64_b_1984_common.blk
```

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

### Manage Sound Events

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/soundSystem/sound

Functions to control the lifecycle and state of sound events. This includes releasing events, setting their 3D attributes and variables, setting and getting timeline positions, starting playback, keying off sounds, abandoning events with a delay, and checking if a sound is currently playing.

```DagorScript
function sound_release_event(_event_handle_)
function sound_set_3d_attr(_event_handle_ , _& pos_)
function sound_set_var(_event_handle_ , _var_name_ , _value_)
function sound_set_timeline_pos(_event_handle_ , _position_)
function sound_get_timeline_pos(_event_handle_)
function sound_start(_event_handle_)
function sound_keyoff(_event_handle_)
function sound_abandon(_event_handle_ , _delay_)
function sound_is_playing(_event_handle_)
```

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

### Launch Level via Launcher for daNetGame Projects

Source: https://gaijinentertainment.github.io/DagorEngine/assets/about-assets/how-to-test-assets-on-maps/how_to_test_assets_on_maps

This outlines the steps to launch a level using the game launcher for daNetGame-based projects. It involves running a batch file, selecting the mission, customizing settings, and then clicking 'Play'.

```text
1. Run `/enlisted/game/z_enlisted_launcher.bat`
2. Select the correct mission from the dropdown (the one with your exported map). Customize mode, graphics settings, etc., if needed.
3. Click **Play** to launch the game.
```

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

### Additional Resource Pack Parameter Example - Dagor Engine

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/folder_blk

Demonstrates how to specify additional resource pack names or use a wildcard to include content in the root pack. This controls where additional assets are placed.

```dagor_config
package:t="outer_space"

```

```dagor_config
package:t="*"

```

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

### Enable Compression Settings

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/application_blk

Enables specific compression algorithms for asset handling. `preferZSTD` and `preferZLIB` allow the engine to utilize these compression methods.

```text
preferZSTD:b=yes
preferZLIB:b=no
```

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

### Declare Network Event in C++ (Example)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-ecs/schemeful_events

An example of declaring a C++ network event with routing information.

```cpp
ECS_REGISTER_NET_EVENT(EventUserMarkDisabled, net::Er::Unicast, net::ROUTING_SERVER_TO_CLIENT, (&rcptf::entity_ctrl_conn<EventUserMarkDisabledNetMsg, rcptf::TARGET_ENTITY>));
```

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

### Build HTML Documentation with Sphinx

Source: https://gaijinentertainment.github.io/DagorEngine/dagor-home/documentation/how_to_build_docs_locally

Builds the HTML documentation using Sphinx. This command specifies the configuration directory, builder type (HTML), source directory, and output directory.

```bash
sphinx-build -c . -b html source _build/html
```

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

### Gizmo Client Interface: Get Position (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Interface method to retrieve the current position of the Gizmo. This is used by the Gizmo client to get its own coordinates.

```C++
virtual Point3 getPt() = 0;

```

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

### Create a Simple Proxy Material .blk File

Source: https://gaijinentertainment.github.io/DagorEngine/assets/materials/proxymats

This example demonstrates the structure of a minimal proxy material .blk file. It omits the material name and enclosing brackets found in a standard .dag file material definition, containing only the material's class and properties.

```blk
class:t="rendinst_emissive"
twosided:b=0
power:r=32
script:t="emissive_color=1,0.1,0.2,8"
tex0:t="emissive_a_tex_d.tif"
tex2:t="emissive_a_tex_n.tif"

```

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

### Get Editor Core Instance (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Static function to get the singleton instance of the IEditorCore interface. This is the main entry point for editor functionalities.

```cpp
static IEditorCore &make_instance();

```

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

### ResourceBarrierDesc Constructors (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/d3dAPI/Barrier

Demonstrates various constructors for the ResourceBarrierDesc class, enabling initialization with single buffers, arrays of buffers, initializer lists of buffers, single textures, arrays of textures, initializer lists of textures, and raytracing acceleration structures. These constructors handle different data layouts and types for resource barrier descriptions.

```cpp
#include <dag_barrier.h>

// Default constructor
ResourceBarrierDesc defaultDesc;

// Constructor with a single buffer
Sbuffer* myBuffer = nullptr; // Assume myBuffer is initialized
ResourceBarrier barrier = ResourceBarrier(); // Assume barrier is initialized
ResourceBarrierDesc bufferDesc(myBuffer, barrier);

// Constructor with an array of buffers
Sbuffer* bufferArray[] = {myBuffer};
ResourceBarrier barrierArray[] = {barrier};
ResourceBarrierDesc bufferArrayDesc(bufferArray, barrierArray, 1);

// Constructor with initializer lists of buffers
ResourceBarrierDesc bufferListDesc({myBuffer}, {barrier});

// Constructor with a single texture
BaseTexture* myTexture = nullptr; // Assume myTexture is initialized
ResourceBarrierDesc textureDesc(myTexture, barrier, 0, 1);

// Constructor with an array of textures
BaseTexture* textureArray[] = {myTexture};
unsigned subResIndexArray[] = {0};
unsigned subResRangeArray[] = {1};
ResourceBarrierDesc textureArrayDesc(textureArray, barrierArray, subResIndexArray, subResRangeArray, 1);

// Constructor with initializer lists of textures
ResourceBarrierDesc textureListDesc({myTexture}, {barrier}, {0}, {1});

// Constructor with a single bottom level acceleration structure
RaytraceBottomAccelerationStructure* myBlas = nullptr; // Assume myBlas is initialized
ResourceBarrierDesc blasDesc(myBlas);

// Constructor with an array of bottom level acceleration structures
RaytraceBottomAccelerationStructure* blasArray[] = {myBlas};
ResourceBarrierDesc blasArrayDesc(blasArray, 1);

```

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

### UI and Tool Management

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Methods for initializing, closing, and filling the User Interface, including toolbars and property panels.

```APIDOC
## UI and Tool Management

### Description
APIs for managing the editor's user interface, including toolbars, property panels, and window events.

### Methods

#### `initUi(int toolbar_id)`
- **Description**: Initialize the User Interface of an Object Editor.
- **Parameters**:
  - `toolbar_id` (int) - In - The toolbar's ID to use.

#### `closeUi()`
- **Description**: Close the User Interface of an Object Editor.

#### `fillToolBar(PropPanel::ContainerPropertyControl *toolbar)`
- **Description**: Fill the ToolBar with buttons (called from `initUi()`). Override to add custom buttons to the toolbar.
- **Parameters**:
  - `toolbar` (PropPanel::ContainerPropertyControl*) - Required - The toolbar container to populate.

#### `createEditorPropBar(void *handle)`
- **Description**: Creates an editor property bar.
- **Parameters**:
  - `handle` (void*) - Required - Handle for the property bar.
- **Returns**: Pointer to the created `ObjectEditorPropPanelBar`.

#### `saveEditorPropBarSettings()`
- **Description**: Saves the settings of the editor property bar.

#### `onWmCreateWindow(int type)`
- **Description**: Handles window creation events.
- **Parameters**:
  - `type` (int) - Required - The type of window to create.
- **Returns**: A pointer to the created window, or `nullptr` if creation fails.

#### `onWmDestroyWindow(void *window)`
- **Description**: Handles window destruction events.
- **Parameters**:
  - `window` (void*) - Required - Pointer to the window being destroyed.
- **Returns**: `true` if the window was successfully destroyed, `false` otherwise.

#### `onClick(int pcb_id, PropPanel::ContainerPropertyControl *panel)`
- **Description**: Handles click events within a property panel.
- **Parameters**:
  - `pcb_id` (int) - Required - The ID of the control that was clicked.
  - `panel` (PropPanel::ContainerPropertyControl*) - Required - The property panel containing the control.

#### `onChange(int pcb_id, PropPanel::ContainerPropertyControl *panel)`
- **Description**: Handles change events within a property panel.
- **Parameters**:
  - `pcb_id` (int) - Required - The ID of the control whose value changed.
  - `panel` (PropPanel::ContainerPropertyControl*) - Required - The property panel containing the control.

```

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

### Image Rasterization Usage Examples in daRg

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-engine-docs/picture_image/Image

Provides practical examples of using the image rasterization syntax within the daRg scripting language. These examples demonstrate how to specify dimensions, aspect ratios, and alpha blending for different image sources, including base64 encoded strings.

```darg
Picture("image.svg:256:256:K:P")
Picture("b64://<base64 encoded string of svg or png>:256:256:K:P")
Picture("image.png:0:P")
Picture("image.png:512:256:P:F")
```

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

### Get Editor Core Instance (C++)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Provides static methods to get and set the current editor core engine instance. This is crucial for accessing editor functionalities and managing its state.

```cpp
static inline IEditorCoreEngine *get() {
    // Get pointer to current editor core instance.
    return nullptr; // Placeholder for actual implementation
}

static inline void set(IEditorCoreEngine *eng) {
    // Set current editor core instance.
    // eng: pointer to the editor core instance
}
```

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

### Export Prefix Parameter Example - Dagor Engine

Source: https://gaijinentertainment.github.io/DagorEngine/assets/all-about-blk/folder_blk

Illustrates setting a prefix for texture pack or game resource pack names. This is useful for organizing assets into subdirectories within the game's resource structure.

```dagor_config
ddsxTexPackPrefix:t="aircrafts/"

```

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

### Retrieve Sound Information

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/soundSystem/sound

Functions to get information about sound assets. This includes retrieving the length of a sound by its name and getting the current state or name of a stream.

```DagorScript
function sound_get_length(_name_)
function sound_get_stream_state(_stream_handle_)
function sound_get_stream_state_name()
```

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

### Start Sound Event Playback

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/quirrel_gamelibs/sound

Initiates the playback of a sound event that has been previously initialized and configured. This function starts the sound playing according to its settings.

```squirrel
function sound_start(event_handle) {
  // Arguments:
  //   event_handle: sndsys::sound_handle_t
  // Returns:
  //   null
}

```

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

### BasicResourceDescription Struct

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/d3dAPI/Heap

Basic resource description containing common fields for all GPU resource types.

```APIDOC
## struct BasicResourceDescription

### Description
Basic resource description that contains common fields for all GPU resource types.

### Public Members
* **cFlags** (uint32_t) - The resource creation flags.
* **activation** (ResourceActivationAction) - The resource activation action.
* **clearValue** (ResourceClearValue) - The clear value.
```

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

### Retrieve Sound Information

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/quirrel_gamelibs/sound

Functions to get information about sound assets. This includes retrieving the length of a sound by its name and getting the current timeline position of a sound event.

```DagorScript
function sound_get_length(_name_)
function sound_get_timeline_pos(_event_handle_)
```

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

### Get Primary Screen Info (dagor.system)

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/quirrel-modules/quirrel-modules/quirrel_gamelibs/dagor.system

Retrieves information about the primary display screen. This function is part of the 'dagor.system' module and can be used to get screen dimensions and other relevant details.

```plaintext
function get_primary_screen_info()
     

```

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

### Light Source Composite File Naming Convention

Source: https://gaijinentertainment.github.io/DagorEngine/assets/lighting/lights_creation_guide

This example illustrates the naming convention for composite files that include light sources. It highlights the importance of specifying the light source functionality and its radius in the file name for clarity and organization.

```plaintext
factory_lamp_a_flicker_10m_cmp.composit.blk
```

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

### Shader Variable Calculation Example

Source: https://gaijinentertainment.github.io/DagorEngine/assets/shaders/rendinst_perlin_layered

Demonstrates how global and static shader variables are combined to determine the final rendering properties of an asset. It shows a practical example of calculating blend sharpness for an asset.

```plaintext
Global shadervar: ri_hmap_blend_sharpness = 8.0
Asset static shadervar: script:t="ri_hmap_blend_sharpness_mul = 0.5"
Final blend sharpness: blend_sharpness = ri_hmap_blend_sharpness * ri_hmap_blend_sharpness_mul = 8.0 * 0.5 = 4
```

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

### Enable Painting for Water-Based Assets (daNetGame)

Source: https://gaijinentertainment.github.io/DagorEngine/assets/about-assets/procedural-rendinst-painting/procedural_rendinst_painting

For assets positioned on water, such as a yacht on a bay, the `script:t="use_painting=2"` parameter must be specified. This ensures correct painting behavior and prevents potential issues. This parameter is crucial for assets that interact with water surfaces.

```plaintext
script:t="use_painting=2"
```

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

### Updated Collision Processing with Includes (.folder.blk)

Source: https://gaijinentertainment.github.io/DagorEngine/assets/collisions/static_object_collision

Demonstrates the current method for collision processing in .folder.blk files, which relies on including pre-defined asset files. This approach ensures consistent application of parameters like geometry optimization and FastRayTracer building.

```blk
virtual_res_blk{
  find:t="^(.*)\.lod02\.dag$"
  className:t="collision"
  name:t="$1_collision"
  contents{
    include "#/develop/assets/_ri_collision_props.blk"
  }
}
```

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

### BasicMap Get Value

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/d3dAPI/ShaderModelVersions

Retrieves the stored value from the BasicMap. The `get` function attempts to move the stored value into the provided receiver `o` or calls the provided generator `c`. It returns true if a value was successfully retrieved or generated and moved.

```cpp
inline bool get(T &o)
{
    // Get value implementation details
    // Returns true if value was stored and moved into o
}
```

```cpp
template<typename C>
inline bool get(C &&c)
{
    // Get value implementation details
    // Returns true if value was stored and c was called
}
```

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

### DSHL Stream Output Example for SV_POSITION and COLOR

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-dshl/index/stream_output

An example demonstrating how to use multiple `#pragma stream_output` directives to define stream output for SV_POSITION.xy and COLOR.yz to a buffer bound to slot 0.

```dshl
#pragma stream_output 0 SV_POSITION XY
#pragma stream_output 0 COLOR YZ
```

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

### Editor Initialization and Core Functions

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

This section covers essential editor functions, including initialization, handling menu item clicks, and retrieving core editor data and systems.

```C++
virtual void init(const char *select_workspace = nullptr)

int onMenuItemClick(unsigned id) override

int getMaxRTSize()

void init(const char *select_workspace = nullptr)
```

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

### Dagor Engine Configuration: Skin Modifier and Bone Limits

Source: https://gaijinentertainment.github.io/DagorEngine/projects/dng/dng_non_human_char

Example configuration for the `application.blk` file, specifying settings for the Skin modifier, including the number of bones per vertex and maximum bone count limitations relevant for asset building.

```ini
dynModel{
  descListOutPath:t="dynModelDesc"
  separateModelMatToDescBin:b=yes

  ignoreMappingInPrepareBillboardMesh:b=yes
  enableMeshNodeCollapse:b=no
  maxBonesCount:i=318   /* This is ineffective! Shader limitations cap bone count at 200.
                           Exceeding 200 will result in errors during daBuild. */
  setBonePerVertex:i=4  // Number of bones per vertex
}
```

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

### Get Texture Streaming Generation and Metadata

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-render/index/resMgr/textures

Provides functions to retrieve the generation of managed texture content, which changes during streaming, and to get the texture meta data for a given texture ID. Also includes a function to validate texture IDs.

```cpp
uint16_t get_managed_texture_streaming_generation(TEXTUREID tid)
{
    // Implementation details...
    return 0;
}
```

```cpp
bool is_managed_texture_id_valid(TEXTUREID tid, bool validate_value)
{
    // Implementation details...
    return true;
}
```

```cpp
TextureMetaData get_texture_meta_data(TEXTUREID id)
{
    // Implementation details...
    return TextureMetaData{};
}
```

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

### SelWindow Methods and Properties

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Methods and properties for the selection window used for choosing objects.

```APIDOC
## SelWindow

### Description
Manages the selection window UI for choosing objects.

### Methods
- `SelWindow()`: Constructor for SelWindow.
- `~SelWindow()`: Destructor for SelWindow.
- `showDialog()`: Displays the selection dialog.
- `getSelectedNames()`: Retrieves the names of the selected objects.
- `ctorInit()`: Initializes the window during construction.
- `fillNames()`: Populates the object list with names.
- `onChange()`: Handler for selection changes.
- `onClick()`: Handler for single clicks on objects.
- `onDoubleClick()`: Handler for double clicks on objects.

### Properties
- `objListName` (string): Name of the object list.
- `objects` (array): List of selectable objects.
- `typeNames` (array): List of type names.
- `typesBlk` (object): Block containing type information.
```

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

### Accelerator and Menu Input

Source: https://gaijinentertainment.github.io/DagorEngine/api-references/dagor-tools/EditorCore/EditorCore

Methods for registering viewport accelerators and handling menu item clicks.

```APIDOC
## Accelerator and Menu Input

### Description
Handles the registration of keyboard accelerators for viewport interactions and processes menu item clicks.

### Methods

#### `registerViewportAccelerators(IWndManager &wndManager)`
- **Description**: Registers accelerators for viewport interactions.
- **Parameters**:
  - `wndManager` (IWndManager&) - Required - The window manager to register accelerators with.

#### `onMenuItemClick(unsigned id)`
- **Description**: Handles clicks on menu items.
- **Parameters**:
  - `id` (unsigned) - Required - The ID of the menu item that was clicked.
- **Returns**: An integer indicating the result of the click handling.

```

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

### Dagor Engine Material Configuration Example

Source: https://gaijinentertainment.github.io/DagorEngine/assets/shaders/land_mesh_combined_decal_family

A complete example of a material configuration in Dagor Engine, demonstrating the use of various parameters including name, class, detail texture offsets, and texture assignments.

```plaintext
material{
  name:t="markup_1"
  class:t="land_mesh_combined_mixed_decal"
  script:t="detail1_size_ofs=128,64,0,0"
  script:t="detail2_size_ofs=128,64,0,0"
  script:t="detail3_size_ofs=128,64,0,0"
  script:t="detail4_size_ofs=256,128,0,0"
  tex0:t="afghan_airfield_bagram_tex.tif"
  tex1:t="afghan_airfield_bagram_tex_mask.tif"
  tex3:t="detail_asphalt_a_tex_d.tif"
  tex4:t="detail_asphalt_a_tex_r.tif"
  tex5:t="detail_concrete_tex_d.tif"
  tex6:t="detail_concrete_tex_r.tif"
  tex7:t="detail_concrete_tex_d.tif"
  tex8:t="detail_asphalt_cracks_tex_r.tif"
  tex9:t="detail_sand_ground_tex_d.tif"
  tex10:t="detail_sand_ground_tex_r.tif"
}
```
Tokens:
Raw