Skip to content

Lua API: 5. RenderEntity, TextRenderEntity

Jump to bottom
MCUmbrella edited this page Nov 28, 2023 · 1 revision

RenderEntity

Properties

x, y

Coordinates of the center of the entity. It is also the center of the texture when the entity is created.

Type: Number (floating-point)

Example:

--[[
  Assume your project is called "MyGame" and you have a texture file at:
  "MyGame/assets/textures/entity/player.png".
  The following code shows the texture on the screen and makes it move down to
  the right from the upper-left corner of the window.
]]--

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
end

function tick()
  player.x = player.x + 1
  player.y = player.y + 1
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

textureWidth, textureHeight

The size of the texture when it is rendered. The texture will be stretched if it is different from the original size.

Type: Number (integer)

Example:

--[[
  Same environment as before,
  the texture grows larger from the center of the window
]]--

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player.x = Window.getWidth() / 2
  player.y = Window.getHeight() / 2
end

function tick()
  player.textureWidth = player.textureWidth + 1
  player.textureHeight = player.textureHeight + 1
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

textureOffsetX, textureOffsetY

Controls how many pixels the texture is offset relative to its center position at creation.

Type: Number (integer)

Example:

--[[
  Same environment as before,
  the texture circles around the center of the screen
]]--

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player.x = Window.getWidth() / 2
  player.y = Window.getHeight() / 2
end

function tick()
  t = Engine.currentTick()
  player.textureOffsetX = math.floor(math.sin(t / 30) * 100)
  player.textureOffsetY = math.floor(math.cos(t / 30) * 100)
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

textureDegree

Degrees of texture rotation. Positive numbers indicate clockwise rotation, negative numbers indicate counterclockwise rotation.

Type: Number (floating-point)

Example:

--[[
  Same environment as before,
  the texture rotates in the center of the screen
]]--

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player.x = Window.getWidth() / 2
  player.y = Window.getHeight() / 2
end

function tick()
  player.textureDegree = player.textureDegree + 1
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

textureRed, textureGreen, textureBlue

The brightness of each color channel of the entity's texture, from 0 (blacked out) to 255 (rendered as is).

Type: Number (integer)

Example:

-- Gives the texture a colorful gradient effect

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player.x = Window.getWidth() / 2
  player.y = Window.getHeight() / 2
end

function tick()
  t = Engine.currentTick()
  player.textureRed = math.floor(128 + math.sin(t / 20) * 128)
  player.textureGreen = math.floor(128 + math.cos(t / 20) * 128)
  player.textureBlue = math.floor(128 - math.sin(t / 20) * 128)
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

textureAlpha

The opacity of the entity's texture, from 0 (invisible) to 255 (completely visible).

Type: Number (integer)

Example:

-- Make the texture loop fade in and out

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player.x = Window.getWidth() / 2
  player.y = Window.getHeight() / 2
end

function tick()
  t = Engine.currentTick()
  player.textureAlpha = math.floor(128 + math.sin(t / 20) * 128)
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

Member functions

getId

Get the ID of the entity.

Return: Poisitive integer, which indicates the the entity's ID.

setLocation

Parameter:

  • Number x
  • Number y

Example:

player:setLocation(newX, newY)
-- Equals to:
player.x = newX
player.y = newY

move

Parameter:

  • Number dx
  • Number dy

Example:

player:move(dx, dy)
-- Equals to:
player.x = player.x + dx
player.y = player.y + dy

setTextureOffset

Parameter:

  • Number x
  • Number y

Example:

player:setTextureOffset(newX, newY)
-- Equals to:
player.textureOffsetX = newX
player.textureOffsetY = newY

moveTexture

Parameter:

  • Number dx
  • Number dy

Example:

player:moveTexture(dx, dy)
-- Equals to:
player.textureOffsetX = player.textureOffsetX + dx
player.textureOffsetY = player.textureOffsetY + dy

rotate

Parameter:

  • Number d

Example:

player:rotate(d)
-- Equals to:
player.textureDegree = player.textureDegree + d

setTextureSize

Parameter:

  • Number w
  • Number h

Example:

player:setTextureSize(w, h)
-- Equals to:
player.textureWidth = w
player.textureHeight = h

resetTextureSize

Reset the width and height of the entity to the actual width and height of the texture.

setTexture

Change the texture used by the entity.

Parameter:

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

getFlip

Get the flip state of the entity's texture.

Return:

  • 0: No flip
  • 1: Horizontal
  • 2: Vertical

setFlip

Set the flip state of the entity's texture.

Parameter: Number state: The flip state (see getFlip() above).

Example:

-- Make the texture flip horizontally every half second

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player:setLocation(Window.getWidth() / 2, Window.getHeight() / 2)
end

function tick()
  t = Engine.currentTick()
  if (t % 60 < 30)
  then
    player:setFlip(1)
  else
    player:setFlip(0)
  end
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

setCrop

Crop the texture used by the entity with a rectangular range.

Parameter:

  • Number startX, startY: Coordinates of the upper left corner of the rectangle
  • Number dx, dy: The width and height of the rectangle

Throw:

  • IllegalArgumentException: when any parameter is negative.

Example:

-- Crop the texture so that only four pixels remain in the upper left corner

function prepare()
  RenderManager.loadTexture("entity/player.png")
  lr = RenderManager.getLayer(0)
  player = lr:addEntity("entity/player.png")
  player:setLocation(Window.getWidth() / 2, Window.getHeight() / 2)
  player:setCrop(0, 0, 2, 2)
  player:setTextureSize(32, 32) -- enlarge the texture for easier viewing
end

function tick()
  -- nothing to do
end

function cleanup()
  lr:clear()
  RenderManager.unloadTexture("entity/player.png")
end

resetCrop

Reset the crop state of the entity's texture.

Example:

player:resetCrop()
-- Equals to:
player:setCrop(0, 0, 0, 0)

TextRenderEntity

TextRenderEntity is a subclass of RenderEntity, and is designed to be used exclusively for storing and rendering text. It has all the properties and member functions that belong to RenderEntity.

CAUTION: All of the above documentation applies to this class as well, except for setTexture(): this class takes over texture management, so calling setTexture() on TextRenderEntity instances will cause error.

Member functions

getContent

Get the content of the text entity.

Return: The text that the entity stores.

setContent

Set the content of the text entity.

Parameter:

  • String content: The new content to set.

Example:

--[[
  Display "Hello world!" and the current tick count in green in the center of
  the window. This example doesn't load or unload any external resources.
]]--

function prepare()
  lr = RenderManager.getLayer(0)
  -- creates a text entity using default font and default size
  txt = lr:addText("")
  --[[
    The text color of the newly created text entity is pure white, mask the red
    and blue color channels to give the effect of making it green.
  ]]--
  txt.textureRed = 0
  txt.textureBlue = 0
end

function tick()
  -- update the content of the text entity
  txt:setContent("Hello world! " .. Engine.currentTick())
  -- centers the text
  txt:setLocation(Window.getWidth() / 2, Window.getHeight() / 2)
end

function cleanup()
  lr:clear()
end
Clone this wiki locally