Lua API: 3. RenderManager

RenderManager

How The Render Manager do rendering

After the tick() function is executed, the window content will be first filled by a background color. After then, several layers (called RenderLayer) are applied. Each layer is (by default) transparent and contains entities (called RenderEntity).

RenderEntities are the smallest unit in the rendering process that you can control, and each entity contains information about the texture it uses, its position, size, and so on. During the apply process of RenderLayer, the texture used by the entity will be placed according to the information that the entity records.

Layers are applied in order from smallest to largest according to the order specified when they are created, which means that if an area in the window content is occupied by two entities that exist on different layers, the entity on the layer with the larger order will occlude the other one.

ChatGPT-polished overview:

Upon executing the tick() function, the Render Manager initializes rendering by filling the window content with a background color. Subsequently, transparent layers, each containing RenderEntities, are applied. RenderEntities serve as the fundamental rendering units, encompassing texture information, position, and size. As layers are applied sequentially based on their creation order, entities on higher-order layers take precedence, potentially occluding those on lower-order layers.

Structure:

Window:
- RenderLayer #0:
  - RenderEntity 1
  - RenderEntity 2
  - ...
- RenderLayer #1:
  - RenderEntity 1
  - RenderEntity 2
  - ...
...

Static functions:

setBackgroundColor

Set the background color.

Parameter:

• Number r: The red amount, integer from 0 to 255.
• Number g: The green amount.
• Number b: The blue amount.

Example:

-- Put this into tick() to see rainbow
t = Engine.currentTick()
RenderManager.setBackgroundColor(
  math.floor(128 + math.sin(t / 20) * 128),
  math.floor(128 + math.cos(t / 20) * 128),
  math.floor(128 - math.sin(t / 20) * 128)
)

loadTexture

Load a texture from file.

Parameter:

• String path: The relative path of the texture, starts from "(user project folder)/assets/textures/".

Example:

--[[
  Assume you have a project called "MyGame", and an image is located in:
  "MyGame/assets/textures/entity/player.png",
  the following code loads it into the render manager for further use.
]]--
RenderManager.loadTexture("entity/player.png")

If the texture at the specified path has already been loaded before, this function does nothing.

If the texture at the specified path does not exist or failed to load for some reason (like no permission, file corrupted, file format is not supported, etc.), then the placeholder texture at "the_engine/assets/textures/placeholder.png" (a 2x2 purple and black checkerboard by default) will be used in the future when this texture is used.

unloadTexture

Unload a previously loaded texture.

Parameter:

• String path: The relative path of the texture, starts from "(user project folder)/assets/textures/".

Example:

-- Unload the texture that has been loaded in the previous example
RenderManager.unloadTexture("entity/player.png")

If the texture at the specified path has not been loaded before, this function does nothing.

addLayer

Add a layer to the window.

Parameter:

• Number order: Integer, which indicates the order of the layer. Cannot be 0 as the layer #0 is automatically created.

Return: The created layer's RenderLayer instance.

Throw:

• EngineException: when the layer with the specified order already exists.

Example:

-- Create 2 layers
layerEntities = RenderManager.addLayer(1)
layerCursor = RenderManager.addLayer(2147483647)

-- This will cause a crash
layerBackground = RenderManager.addLayer(0) -- error: already exists

-- This will also cause a crash
layerSky = RenderManager.addLayer(-1)
layerSky = RenderManager.addLayer(-1) -- error: already exists

removeLayer

Remove a previously added layer.

Parameter:

• Number order: The order of the layer. Cannot be 0.

Throw:

• EngineException: when
  • the layer with the specified order doesn't exists
  • parameter "order" is 0

Example:

-- Remove the layers added in the previous example.
RenderManager.removeLayer(1) -- removes layerPlayer
RenderManager.removeLayer(2147483647) -- removes layerCursor

getLayer

Get the instance of the layer with the specified order.

Parameter:

• Number order: The order of the layer.

Return: The instance of the layer with the specified order.

Throw:

• EngineException: when the layer with the specified order doesn't exists.

Example:

-- Get the default layer
layer0 = RenderManager.getLayer(0)

hasLayer

Check if a layer with the specified order exists.

Parameter:

• Number order: The order of the layer.

Return: true if so, false otherwise.

Example:

Runtime.log("Layer #0 exists? " .. tostring(RenderManager.hasLayer(0)))

--[[
  Does layer #6 exist?
  If yes, get it as variable "lr6",
  if no, create it and get as variable "lr6"
]]--
lr6 = RenderManager.hasLayer(6) and RenderManager.getLayer(6) or RenderManager.addLayer(6)

--[[
  Equals to:
  lr6 = RenderManager.hasLayer(6) ? RenderManager.getLayer(6) : RenderManager.addLayer(6)
  There's no ?: operator in Lua, so sad
]]--

loadFont

Load a custom TTF font file into the render manager.

Parameter:

• String name: The friendly name of the font, for further use in your scripts.
• String path: The relative path of the font, starts from "(user project folder)/assets/fonts/".

Throw:

• EngineException: when
  • the font has failed to load
  • the font with the specified name already exists
  • parameter "name" is empty string

Example:

--[[
  Same environment as before, an TTF file is located in:
  "MyGame/assets/fonts/DejaVuSansMono.ttf",
  the following code loads it into the render manager for further use.
]]--
RenderManager.loadFont("dejavu", "DejaVuSansMono.ttf")

unloadFont

Unload a previously loaded font.

Parameter:

• String name: The name of the font that you named it before.

Throw:

• EngineException: when
  • the font with the specified name doesn't exists
  • parameter "name" is empty string

Example:

-- Unload "DejaVuSansMono.ttf" in the previous example
RenderManager.unloadFont("dejavu")

hasFont

Check if a font with the specified name has been loaded.

Parameter:

• String name: The friendly name of the font.

Return: true if so, false otherwise.

This function always return true when the argument is empty string, as the friendly name of the default font is empty string.