Spring Engine Documentation

https://recoilengine.org/docs
Admin
This project provides comprehensive documentation and guides for the Spring Engine, covering its Lua...
Tokens:37,807
Snippets:702
Trust Score:4.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Portable Setup Example

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Combining isolation and write directory settings for a portable game setup, reading from one location and writing to another.

```bash
./spring --isolation --isolation-dir /media/game --write-dir /home/user/saves
```

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

### Example Gadget Handler Implementation

Source: https://recoilengine.org/docs/guides/getting-started/widgets-and-gadgets

A simplified pseudocode example illustrating how a gadget handler might register and manage gadgets, and distribute callins like 'Update'.

```lua
--- @class GadgetHandler
--- @field gadgets Gadget[]
GadgetHandler = {
    gadgets = {},
    shared_table = {}
}

--- @param file string filepath to gadget
function register_gadget(file)
    if not VFS.FileExists(filename) then
        return {}
    end
    
    local gadget_env = {}
    gadget_env.shared_table = GadgetHandler.shared_table
    local success, rvalue = pcall(VFS.Include, filename, gadget_env)
    if success then
        return gadget_env.gadget
    end
    
    return {}
end

--- @param file string filepath to gadget
function GadgetHandler:add_gadget(file)
    local new_gadget = register_gadget(file)
    table.insert(GadgetHandler.gadgets, new_gadget)
end

--- @param delta number
function Update(delta)
    for _, gadget in GadgetHandler.gadgets do
        if gadget:Update then
            gadget:Update(delta)
        end
    end
end

Spring.UpdateCallin('Update')

GadgetHandler:add_gadget("luarules/gadgets/testwidget.lua")
```

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

### Include RmlUi Setup Script

Source: https://recoilengine.org/docs/guides/getting-started/getting-started-with-rmlui

This command includes the RmlUi setup script from the specified path, ensuring RmlUi is properly initialized before use.

```lua
VFS.Include(LUAUI_DIRNAME .. "rml_setup.lua",  nil, VFS.ZIP) -- Runs the script
```

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

### Clone VroomRTS for Development

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Clone a simple gameplay example game directly into your games/ directory with the .sdd extension.

```bash
cd recoil-engine/games/
git clone https://github.com/DarkBlueDiamond/VroomRTS.git VroomRTS.sdd
```

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

### Enable Isolated Mode with isolated.txt

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Setting up isolated mode by creating an 'isolated.txt' file in the engine directory for portable installations.

```text
your-game/
├── recoil-executable
├── isolated.txt      # Create this file
├── games/
├── maps/
└── base/
```

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

### RmlUi Setup Script

Source: https://recoilengine.org/docs/guides/getting-started/getting-started-with-rmlui

This Luau script initializes RmlUi, creates a shared context, and sets up mouse cursor aliases. It's designed to be included in your main Lua entry point.

```lua
--  luaui/rml_setup.lua
--  author:  lov + ChrisFloofyKitsune
--
--  Copyright (C) 2024.
--  Licensed under the terms of the GNU GPL, v2 or later.

if (RmlGuard or not RmlUi) then
	return
end
-- don't allow this initialization code to be run multiple times
RmlGuard = true

--[[ 
	Recoil uses a custom set of Lua bindings (check out rts/Rml/SolLua/bind folder in the C++ engine code)
	Aside from the Lua API, the rest of the RmlUi documentation is still relevant
		https://mikke89.github.io/RmlUiDoc/index.html
]]

--[[ create a common Context to be used for widgets
	pros:
		* Documents in the same Context can make use of the same DataModels, allowing for less duplicate data
		* Documents can be arranged in front/behind of each other dynamically
	cons:
		* Documents in the same Context can make use of the same data models, leading to side effects
		* DataModels must have unique names within the same Context

	If you have lots of DataModel use you may want to create your own Context
	otherwise you should be able to just use the shared Context

	Contexts created with the Lua API are automatically disposed of when the LuaUi environment is unloaded
]]

local oldCreateContext = RmlUi.CreateContext

local function NewCreateContext(name)
	local context = oldCreateContext(name)

	-- set up dp_ratio considering the user's UI scale preference and the screen resolution
	local viewSizeX, viewSizeY = Spring.GetViewGeometry()

	local userScale = Spring.GetConfigFloat("ui_scale", 1)

	local baseWidth = 1920
	local baseHeight = 1080
	local resFactor = math.min(viewSizeX / baseWidth, viewSizeY / baseHeight)

	context.dp_ratio = resFactor * userScale

	context.dp_ratio = math.floor(context.dp_ratio * 100) / 100
	return context
end

RmlUi.CreateContext = NewCreateContext

-- Load fonts
local font_files = {
}
for _, file in ipairs(font_files) do
	Spring.Echo("loading font", file)
	RmlUi.LoadFontFace(file, true)
end


-- Mouse Cursor Aliases
--[[
	These let standard CSS cursor names be used when doing styling.
	If a cursor set via RCSS does not have an alias, it is unchanged.
	CSS cursor list: https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
	RmlUi documentation: https://mikke89.github.io/RmlUiDoc/pages/rcss/user_interface.html#cursor
]]

-- when "cursor: normal" is set via RCSS, "cursornormal" will be sent to the engine... and so on for the rest
RmlUi.SetMouseCursorAlias("default", 'cursornormal')
RmlUi.SetMouseCursorAlias("pointer", 'Move') -- command cursors use the command name. TODO: replace with actual pointer cursor?
RmlUi.SetMouseCursorAlias("move", 'uimove')
RmlUi.SetMouseCursorAlias("nesw-resize", 'uiresized2')
RmlUi.SetMouseCursorAlias("nwse-resize", 'uiresized1')
RmlUi.SetMouseCursorAlias("ns-resize", 'uiresizev')
RmlUi.SetMouseCursorAlias("ew-resize", 'uiresizeh')

RmlUi.CreateContext("shared")

```

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

### Generate Metal Spots Decals

Source: https://recoilengine.org/docs/guides/rendering/using-decals

Creates multiple ground decals to represent metal spots, applying specific textures and dimensions. This example demonstrates a practical application for generating recurring visual elements.

```lua
local decalTextureIndex = "1" -- Uses `maindecal_1` and `normdecal_1`
local decalSize = 85
local offset = { x = 7, z = 7 }

local decalName = "maindecal_" .. decalTextureIndex
local decalNormalName = "normdecal_" .. decalTextureIndex

-- Decal IDs to clean up or operate on later
local decalIDs = {} ---@type integer[]

function widget:Initialize()
  -- A list of tables with fields z and x
  local spots = {} ---@type ({ x: number, z: number })[]

  for _, spot in ipairs(spots) do
    local x, z = spot.x + offset.x, spot.z + offset.z

    local decalID = Spring.CreateGroundDecal()

    if decalID then
      Spring.SetGroundDecalPosAndDims(decalID, x, z, decalSize, decalSize)

      Spring.SetGroundDecalTexture(decalID, decalName, true)
      Spring.SetGroundDecalTexture(decalID, decalNormalName, false)

      -- store the decalID for cleanup on shutdown
      table.insert(decalIDs, decalID)
    end
  end
end

function widget:Shutdown()
  for _, id in ipairs(decalIDs) do
    Spring.DestroyGroundDecal(id)
  end
end
```

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

### GLSL Fragment Shader Example

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

A basic GLSL fragment shader for Recoil. It takes interpolated texture coordinates and a sampler for the input texture to determine the final fragment color.

```glsl
#version 460

uniform sampler2D inputTexture;

in DataVS {
    vec2 texCoord;
};

out vec4 colorOut; // This is the final fragment color

void main() {
    colorOut = texture(inputTexture, texCoord);
}
```

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

### GLSL Vertex Shader Example

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

A basic GLSL vertex shader for Recoil. It defines input attributes like instance position, vertex position, color, and UV coordinates, and outputs texture coordinates for interpolation.

```glsl
#version 460

//##UBO##
// We'll talk about this later

in vec4 instancePosition;
in vec4 pos; // Note: To project properly, it should be a vec4 with the w value being 1.0
in uvec3 color;
in vec2 uv;

out DataVS {
    vec2 texCoord;
};

void main() {
    gl_Position = cameraViewProj * (instancePosition + pos);
    texCoord = uv;
}
```

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

### Clone RecoilExampleMod for Development

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Clone a beginner-friendly game directly into your games/ directory with the .sdd extension for immediate engine detection.

```bash
cd recoil-engine/games/
git clone https://github.com/DarkBlueDiamond/RecoilExampleMod.git RecoilExampleMod.sdd
```

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

### Get Uniform Location

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

Retrieve the location of a uniform variable in a shader program. This is necessary before you can modify its value.

```lua
local uniform_location = gl.GetUniformLocation(shader, "myUniformName")
```

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

### Creating a Shader with Custom Uniforms

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

Demonstrates how to create a shader and define custom uniform inputs, such as textures.

```lua
shader = gl.CreateShader({
    fragment = VFS.LoadFile("path/to/shader.frag.glsl"),
    vertex = VFS.LoadFile("path/to/shader.vert.glsl"),
    uniformInt = {
        inputTexture = 0, -- we'll get to this
    }
})
```

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

### Launch the Recoil Engine

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

After setting up your games, launch the engine from the command line to select and play them.

```bash
./spring
```

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

### Create and Define VBOs and VAO

Source: https://recoilengine.org/docs/guides/rendering/lua-vbo-vao

Obtain empty VAO and VBO objects, define their structure with attributes and types, and attach them to the VAO. Use 'GL.ARRAY_BUFFER' for vertex/instance data and 'GL.ELEMENT_ARRAY_BUFFER' for indices. Buffers optimized for frequent updates are marked with 'true'.

```lua
local someVAO = gl.GetVAO() --get empty VAO

local vertVBO = gl.GetVBO(GL.ARRAY_BUFFER, true) --empty VBO, "GL.ARRAY_BUFFER" means it's either vertex or instance buffer, "true" means this buffer will be optimized by GL driver for frequent updates. Here by the variable name you can guess it's supposed to be vertex buffer

local instVBO = gl.GetVBO(GL.ARRAY_BUFFER, true) --empty VBO, "GL.ARRAY_BUFFER" means it's either vertex or instance buffer, "true" means this buffer will be optimized by GL driver for frequent updates. Here by the variable name you can guess it's supposed to be instance buffer

local indxVBO = gl.GetVBO(GL.ELEMENT_ARRAY_BUFFER, false) -- empty index buffer, not going to be frequently updated ("false").

vertVBO:Define(1000, {
    {id = 0, name = "pos", size = 4}, -- "pos" attribute will hold 4 floats (float is the default type, if "type" is not specified). "id" in the shader must be 0
    {id = 1, name = "color", type=GL.UNSIGNED_BYTE, normalized = true, size = 3}, -- "color" is represented by 3 unsigned bytes (values from 0 to 255), values are normalized (in this case divided by 255 to get float inside shader). "id" in the shader must be 1. This can be useful to hold RGB data.
})

instVBO:Define(2, {
     {id = 2, name = "posBias", size = 4}, -- posBias is 4 floats attribute of id = 2, note that ids here and ids of vertVBO cannot duplicate. We will use it to offset instances in space
})

indxVBO:Define(2000, GL.UNSIGNED_INT) --defines index buffer with capacity of 2000 elements of type unsigned integer (32 bit integer), other possibilities for type are GL.UNSIGNED_SHORT and GL.UNSIGNED_BYTE, representing 16 bit and 8 bit unsigned integers respectively. If no type is given GL.UNSIGNED_SHORT is the default) - it makes sense as it allows to index 65534 vertices and occupies only 2 bytes per one index.

--here we attach (glue) VBOs into VAO. Note in theory you can use (and I use sometimes) completely empty VAO (no attached buffers), but most often you will want to attach (and create before) at least vertex buffer.
someVAO:AttachVertexBuffer(vertVBO) --note vertVBO and instVBO were created with the same command (except for definition), the only way to tell apart instance buffer from vertex buffer is to see what command was used to attach the VBO to the VAO.
someVAO:AttachInstanceBuffer(instVBO)
someVAO:AttachIndexBuffer(indxVBO)
-- only one attachment of certain type can be made. E.g. you can't attach two vertex buffers.
```

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

### Instancing with Instance Buffer (Lua)

Source: https://recoilengine.org/docs/guides/rendering/lua-vbo-vao

Shows how to use an instance buffer to draw multiple instances of a shape with per-instance data, such as offsets, in Recoil.

```lua
local rect_vertices = {
    -0.5, -0.5, -- bottom-left
     0.5, -0.5, -- bottom-right
     0.5,  0.5, -- top-right
    -0.5,  0.5  -- top-left
}

local instance_offsets = {
    0.0, 0.0, -- instance 1 offset
    1.0, 0.0, -- instance 2 offset
    0.0, 1.0, -- instance 3 offset
    1.0, 1.0  -- instance 4 offset
}

-- Assuming you have functions to create VBOs and set up rendering state
-- local vertex_vbo = create_vbo(rect_vertices)
-- local instance_vbo = create_vbo(instance_offsets, false, true) -- false=vertex, true=instance buffer
-- setup_vertex_and_instance_attributes(vao_description)
-- bind_vbo(vertex_vbo)
-- bind_vbo(instance_vbo)
-- draw_arrays_instanced(4, 4) -- 4 vertices per instance, 4 instances
```

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

### Example Yardmap Definition

Source: https://recoilengine.org/docs/guides/yardmaps

This yardmap defines a building's footprint using characters to represent different areas. 'o' is the building body, and 'y' is open space, forming a diamond shape within a 5x5 footprint.

```plaintext
yyoyy
yoooy
ooooo
yoooy
yyoyy
```

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

### Basic Addon Outline

Source: https://recoilengine.org/docs/guides/getting-started/widgets-and-gadgets

This is a fundamental blueprint for creating both widgets and gadgets. It demonstrates how to define addon information and implement separate logic for synced and unsynced code execution.

```lua
-- There is an injected global called addon/widget/gadget.
local addon = addon

function addon:GetInfo()
    return {
        name = "My addon", -- What it's called (Shows up in addon management menus, if there are any)
        description = "This is an addon", -- Description of your addon.
        author = "Me", -- Who wrote it
        date = "Present day, Present Time! Hahahahaha!", -- Nobody really cares about this.
        license = "GPL 3.0", -- License for other people who want to use your addon. Most code in Recoil games are GPL 3.0 or later.
        layer = 1, -- Affects execution order. Lower is earlier execution, and can go below 0. Useful if addons depend on eachother.
    }
end

-- Actual functional code

if addonHandler:IsSyncedCode() then
    -- Your synced code goes here.
    function addon:Initialize()
        Spring.Echo("We have liftoff!")
    end

    function addon:SomeSyncedCallin()
        Spring.Echo("Synced callin!")
    end

    function addon:Shutdown()
        Spring.Echo("They came from... behind...")
    end
else
    -- Your unsynced code egoes here.
    function addon:Initialize()
        Spring.Echo("My life for the horde!")
    end

    function addon:SomeUnsyncedCallin()
        Spring.Echo("Unsynced callin!")
    end

    function addon:Shutdown()
        Spring.Echo("Arrrgh!!!")
    end
end

```

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

### Create and Configure a Ground Decal

Source: https://recoilengine.org/docs/guides/rendering/using-decals

Creates a new ground decal and sets its position, dimensions, and textures. Use this for basic decal placement.

```lua
local decalID = Spring.CreateGroundDecal() -- create a new decal

if decalID then
  -- posX, posZ refer to a point in world space
  Spring.SetGroundDecalPosAndDims(decalID, posX, posZ, decalWidth, decalHeight)
  Spring.SetGroundDecalTexture(decalID, "maindecal_1")
  -- Comment below if you don't wish to use a normal map
  Spring.SetGroundDecalTexture(decalID, "normdecal_1", false)
end

-- When your decal is not needed anymore
-- Spring.DestroyGroundDecal(decalID)
```

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

### RmlUi Widget Initialization and Management in Lua

Source: https://recoilengine.org/docs/guides/getting-started/getting-started-with-rmlui

This Lua script defines a basic RmlUi widget, handling its initialization, data model setup, document loading, and shutdown. It's designed to be loaded by the RmlUi engine.

```lua
-- luaui/widgets/getting_started.lua
if not RmlUi then
    return
end

local widget = widget ---@type Widget

function widget:GetInfo()
    return {
        name = "Rml Starter",
        desc = "This widget is a starter example for RmlUi widgets.",
        author = "Mupersega",
        date = "2025",
        license = "GNU GPL, v2 or later",
        layer = -1000000,
        enabled = true
    }
end

local document
local dm_handle
local init_model = {
    expanded = false,
    message = "Hello, find my text in the data model!",
    testArray = {
        { name = "Item 1", value = 1 },
        { name = "Item 2", value = 2 },
        { name = "Item 3", value = 3 },
    },
}

local main_model_name = "starter_model"

function widget:Initialize()
    widget.rmlContext = RmlUi.GetContext("shared") -- Get the context from the setup lua

    -- Open the model, using init_model as the template. All values inside are copied.
    -- Returns a handle, which we will touch on later.
    dm_handle = widget.rmlContext:OpenDataModel(main_model_name, init_model)
    if not dm_handle then
        Spring.Echo("RmlUi: Failed to open data model ", main_model_name)
        return
    end
    -- Load the document we wrote earlier.
    document = widget.rmlContext:LoadDocument("luaui/widgets/getting_started.rml", widget)
    if not document then
        Spring.Echo("Failed to load document")
        return
    end

    -- uncomment the line below to enable debugger
    -- RmlUi.SetDebugContext('shared')

    document:ReloadStyleSheet()
    document:Show()
end

function widget:Shutdown()
    widget.rmlContext:RemoveDataModel(main_model_name)
    if document then
        document:Close()
    end
end

-- This function is only for dev experience, ideally it would be a hot reload, and not required at all in a completed widget.
function widget:Reload(event)
    Spring.Echo("Reloading")
    Spring.Echo(event)
    widget:Shutdown()
    widget:Initialize()
end

```

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

### Create Vertex Buffers and VAO

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

Initialize a Vertex Array Object (VAO) and Vertex Buffer Objects (VBOs) for vertex, instance, and index data. Buffers marked as 'true' are optimized for frequent updates.

```lua
local my_vao = gl.GetVAO() -- first, create a VAO

local vert_vbo = gl.GetVBO(GL.ARRAY_BUFFER, true) --empty VBO, "GL.ARRAY_BUFFER" means it's either vertex or instance buffer, "true" means this buffer will be optimized by GL driver for frequent updates. Here by the variable name you can guess it's supposed to be vertex buffer

local instance_vbo = gl.GetVBO(GL.ARRAY_BUFFER, true)

local index_vbo = gl.GetVBO(GL.ELEMENT_ARRAY_BUFFER, false) -- empty index buffer, not going to be frequently updated ("false").
```

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

### Create a Development Game Directory

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Development games can be stored as regular directories with a .sdd extension. No special format or build step is required.

```bash
mkdir MyGame.sdd
```

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

### Set Write Directory via Command Line

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Configuring a specific directory for saves, replays, and logs using the --write-dir command-line option.

```bash
./spring --write-dir /path/to/writable/dir
```

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

### Upload Instance Data

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

Load instance-specific data into the instance buffer. Each element corresponds to an instance and maps to the defined instance attributes.

```lua
instance_vbo:Upload({
    -- element 1
    0.0, 0.0, 0.0, 1.0, -- "position"
    -- element 2
    100.0, 0.0, 100.0, 1.0, -- "position"
})
```

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

### Restore Default Behavior for Spring.GetConfig Functions

Source: https://recoilengine.org/docs/guides/migrating-from-spring

To revert to the previous behavior of treating nil as 0 or "", wrap the `originalGetConfigInt` call with an `or 0`.

```lua
local originalGetConfigInt = Spring.GetConfigInt
Spring.GetConfigInt = function(key, def)
 return originalGetConfigInt(key, def) or 0
end
```

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

### Lua Data Model and Document Loading

Source: https://recoilengine.org/docs/guides/getting-started/getting-started-with-rmlui

Demonstrates how to open a data model and load an RML document in Lua. Ensure the return value of OpenDataModel is assigned to a variable to prevent engine crashes.

```lua
local model = {
    add = function(a, b) 
        Spring.Echo(a + b)
    end
}
local document_table = {
    print = function(msg)
        Spring.Echo(msg)
    end
}

dm_handle = widget.rmlContext:OpenDataModel("test", model)
document = widget.rmlContext:LoadDocument("document.rml", document_table)
```

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

### Basic RmlUi Widget Structure

Source: https://recoilengine.org/docs/guides/getting-started/getting-started-with-rmlui

This snippet shows a basic RmlUi widget structure, including head with styles and body with content. It demonstrates how to define elements, apply styles using IDs and classes, and set up basic layout properties.

```rml
<rml>
<head>
    <title>Rml Starter</title>

    <style>
        #rml-starter-widget {
            pointer-events: auto;
            width: 400dp;
            right: 0;
            top: 50%;
            transform: translateY(-90%);
            position: absolute;
            margin-right: 10dp;
        }
        #main-content {
            padding: 10dp;
            border-radius: 8dp;
            z-index: 1;
        }
        #expanding-content {
            transform: translateY(0%);
            transition: top 0.1s linear-in-out;
            z-index: 0;
            height: 100%;
            width: 100%;
            position: absolute;
            top: 0dp;
            left: 0dp;
            border-radius: 8dp;
            display: flex;
            flex-direction: column;
            justify-content: flex-end;
            align-items: center;
            padding-bottom: 20dp;
        }
        /* This is just a checkbox sitting above the entirety of the expanding content */
        /* It is bound directly with data-checked attr to the expanded value */
        #expanding-content>input {
            height: 100%;
            width: 100%;
            z-index: 1;
            position: absolute;
            top: 0dp;
            left: 0dp;
        }
        #expanding-content.expanded {
            top: 90%;
        }
        #expanding-content:hover {
            background-color: rgba(255, 0, 0, 125);
        }
    </style>
</head>
<body>
    <div id="rml-starter-widget" class="relative" data-model="starter_model">
        <div id="main-content">
            <h1 class="text-primary">Welcome to an Rml Starter Widget</h1>
            <p>This is a simple example of an RMLUI widget.</p>
            <div>
                <button onclick="widget:Reload()">reload widget</button>
            </div>
        </div>
        <div id="expanding-content" data-class-expanded="expanded">
            <input type="checkbox" value="expanded" data-checked="expanded"/>
            <p>{{message}}</p>
            <div>
                <span data-for="test, i: testArray">name:{{test.name}} index:{{i}}</span>
            </div>
        </div>
    </div>
</body>
</rml>
```

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

### Drawing a Rectangle with Index Buffer (Lua)

Source: https://recoilengine.org/docs/guides/rendering/lua-vbo-vao

Demonstrates the use of an index buffer to draw a rectangle efficiently by defining two triangles using indices that reference vertex data.

```lua
local rect_vertices = {
    -0.5, -0.5, -- bottom-left
     0.5, -0.5, -- bottom-right
     0.5,  0.5, -- top-right
    -0.5,  0.5  -- top-left
}

local rect_indices = {
    0, 1, 2, -- first triangle
    2, 3, 0  -- second triangle
}

-- Assuming you have functions to create VBOs and set up rendering state
-- local vertex_vbo = create_vbo(rect_vertices)
-- local index_vbo = create_vbo(rect_indices, true) -- true indicates index buffer
-- setup_vertex_attributes(vao_description)
-- bind_vbo(vertex_vbo)
-- bind_vbo(index_vbo)
-- draw_elements(3, 6) -- 3 primitives, 6 indices
```

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

### Upload Data to VBOs

Source: https://recoilengine.org/docs/guides/rendering/lua-vbo-vao

Upload vertex, instance, and index data to their respective VBOs. The Upload() function can take various arguments for partial updates, but for static data, uploading all at once is recommended.

```lua
local vertexData = {
    -- element #1
    0, 0, 0, 1, --this goes into "pos"
    127, 0, 0, --this goes into "color"
    -- element #2
    1, 1, 1, 1, --this goes into "pos"
    127, 127, 0, --this goes into "color"
    -- element #3
    1, 0, 0, 1, --this goes into "pos"
    127, 127, 127, --this goes into "color"
   -- etc
}
vertVBO:Upload(vertexData)

local instanceData = {
    -- element #1
    100, 100, 0, 1, --this goes into "posBias"
    -- element #2
    100, 200, 0, 1, --this goes into "posBias"
    -- element #3
    200, 100, 0, 1, --this goes into "posBias"
   -- etc
}
instVBO:Upload(instanceData)

local indexData = {
    0, 1, 2, --one triangle
    1, 2, 3, --second triangle
    -- etc
}
indxVBO:Upload(indexData)
```

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

### Rapid Content Delivery System Structure

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

The Rapid system uses a content-addressed storage with specific directories for repository metadata, package indexes, and content files.

```text
data-directory/
├── rapid/                   # Repository metadata
│   └── repos.springrts.com/ # Per-host metadata
│       └── my-game/
│           └── versions.gz   # Tag-to-package mappings
├── packages/                # .sdp index files (archive manifests)
│   └── abc123def.sdp        # One file per archive version
└── pool/                     # Content files, organized by hash
    └── ab/                   # First 2 hex chars of MD5 hash
        └── c123def...gz      # Gzipped file content
```

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

### Define Instance Buffer Layout

Source: https://recoilengine.org/docs/guides/rendering/making-shaders

Define the layout for instance data, specifying the number of instances and the structure of custom data per instance, such as a vec4 for instance position.

```lua
--[[
    Here, we define the instance buffer; Custom data for each instance of an object we want to draw.
    We want to draw 2 objects.
    Each instance gets a vec4 instancePosition.
]]
instance_vbo:Define(2, {
    {id = 0, name = "instancePosition", size = 4},
})
```

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

### Engine Directory Structure

Source: https://recoilengine.org/docs/guides/getting-started/first-steps-with-the-engine

Recommended directory structure for placing game and map archives during development within the engine directory.

```text
recoil-engine/
├── games/          # Your game archives (.sd7, .sdz, .sdd)
├── maps/           # Your map archives
└── base/           # Base content (provided by engine)
```
Tokens:
Raw