ShapeList¶

log("ShapeData names available:")
for _,name in ipairs(ShapeData.GetAllRegistered()) do
    log("    " .. name)
end

-- Check if the shape exists already
if not ShapeData.IsRegistered("myExampleShape") then
    -- It doesn't, so create and register it
    local shape = ShapeData.new()
    shape.positions = { ... }
    shape.lines = { ... }
    local success = ShapeData.Register("myExampleShape", shape)
end

-- Create the shape data first
local shape = ShapeData.new()
shape.positions = { ... }
shape.rgba = { ... }
shape.lines = { ... }

-- Then register it with the desired name
local success = ShapeData.Register("myExampleShape", shape

local success = ShapeData.Unregister("myExampleShape")

-- Alternatively
if ShapeData.IsRegistered("myExampleShape") then

    -- Do some clean-up work
    ...

    -- Then finally unregister
    ShapeData.Unregister("myExampleShape")
end

-- Draw a rotating tile shape on the tile the mouse cursor is pointing at

-- A basic tile shape
local tileShape = ShapeData.new()
tileShape.positions = {
    Vector3.new(-250, 0, -250),
    Vector3.new(250, 0, -250),
    Vector3.new(250, 0, 250),
    Vector3.new(-250, 0, 250)
}
tileShape.lines = { 0, 1, 1, 2, 2, 3, 3, 0 }

-- Track the time elapsed
elapsedTime = 0.0

-- ShapeList.Draw() only works within draw events
Event.Draw.Subscribe("myEvent", function (drawEvent)

    -- Update the time
    elapsedTime = elapsedTime + drawEvent.timeDeltaSecs

    -- Get the coordinate under the mouse cursor
    local coordGrid = ScreenConvert.ScreenToCoordGrid(Mouse.GetPosition())
    if coordGrid ~= nil then

        -- Rotate once every 4 seconds
        local interval = 4.0
        local yaw = 360 * (math.fmod(elapsedTime, interval) / interval)

        -- Get the tile centre
        local tilePos = coordGrid:ToCoordFine(true).position
        -- Find the ground height
        tilePos.y = World.GetGroundHeight(coordGrid.level, tilePos.x, tilePos.z)
        -- Move vertically up to reduce clipping
        tilePos.y = tilePos.y + 100.0

        -- Draw the shape
        ShapeList.Draw( {
            shapeData = tileShape,
            translation = tilePos,
            rotation = Vector3.new(yaw, 0, 0),
            colour = 0xFF8800FF
        } )

    end
end)

-- Draw an orange line showing the player's movement history

-- Small wrapping buffer to hold player coordinates
playerHistoryCoords = {}
playerHistoryMax = 10
function addPlayerCoord(coord)
    if lastCoord == nil or lastCoord ~= coord then
        lastCoord = coord
        local count = #(playerHistoryCoords)
        if count < playerHistoryMax then
            playerHistoryCoords[count + 1] = coord
        else
            for i=1,(playerHistoryMax-1) do
                playerHistoryCoords[i] = playerHistoryCoords[i + 1]
            end
            playerHistoryCoords[playerHistoryMax] = coord
        end
    end
end

-- ShapeList.DrawLine() only works within draw events
Event.Draw.Subscribe("myEvent", function (drawEvent)

    -- Add the current player coordinate to the list
    local playerEntity = Player.GetEntity()
    if playerEntity ~= nil then
        addPlayerCoord(playerEntity.coordGrid)
    end

    -- ShapeList.DrawLine{} requires at least two positions
    if #(playerHistoryCoords) >= 2 then

        -- Build a line of positions from the coords
        local linePositions = {}
        for i,coord in ipairs(playerHistoryCoords) do
            local pos = coord:ToCoordFine(true).position
            pos.y = World.GetGroundHeight(coord.level, pos.x, pos.z) + 50.0
            linePositions[i] = pos
        end

        -- Draw the line of positions
        -- Positions are already in world-space so no need to use the translation setting
        ShapeList.DrawLine( {
            positions = linePositions,
            colour = 0xFF8800FF,
            lineWidth = 6.0
        } )

    end
end)

-- Create an empty instance
local instance = ShapeList.CreateInstance("myInstance");
if instance ~= nil then
    -- Populate with shape data
    instance:SetShapeDataName("myShape")
    -- Move into position, 100 fine units above the ground
    instance.translation = CoordGrid._0_50_50_32_32:ToFine(true).position  + Vector3.new(0, 100, 0)
end

-- Create an instance and set it up
local tmpInstance = ShapeList.CreateInstance("myInstance");
...

-- Get the instance inside the logic event
Event.Logic.Subscribe("myEvent", function (logicEvent)
    local logicInstance = ShapeList.GetInstance("myInstance");
    if logicInstance ~= nil then
        -- Make changes
    end
end)

-- Print every instance name
local allInstances = ShapeList.GetAllInstances()
log("There are " .. #(allInstances) .. " ShapeInstances")
for _,instance in ipair(allInstances) do
    log(instance.name)
end

-- Destroy every instance (by object)
local allInstances = ShapeList.GetAllInstances()
log("Destroying " .. #(allInstances) .. " ShapeInstances")
for _,instance in ipair(allInstances) do
    ShapeList.DestroyInstance(instance)
end

-- Destroy every instance (by name)
local allInstances = ShapeList.GetAllInstances()
log("Destroying " .. #(allInstances) .. " ShapeInstances")
for _,instance in ipair(allInstances) do
    ShapeList.DestroyInstance(instance.name)
end

-- Create an empty entity
local entity = ShapeList.CreateEntity("myEntity");
if entity ~= nil then
    -- Populate with shape data
    entity:SetShapeDataName("myShape")
    -- Move into position, 100 fine units above the ground
    entity.coordGrid = CoordGrid._0_50_50_32_32
    entity.heightOffset = 100
end

-- Create an entity and set it up
local tmpEntity = ShapeList.CreateEntity("myEntity");
...

-- Get the entity inside the logic event
Event.Logic.Subscribe("myEvent", function (logicEvent)
    local logicEntity = ShapeList.GetEntity("myEntity");
    if logicEntity ~= nil then
        -- Make changes
    end
end)

-- Print every entity name
local allEntities = ShapeList.GetAllEntities()
log("There are " .. #(allEntities) .. " ShapeEntities")
for _,entity in ipair(allEntities) do
    log(entity.name)
end

-- Destroy every entity (by object)
local allEntities = ShapeList.GetAllEntities()
log("Destroying " .. #(allEntities) .. " ShapeEntities")
for _,entity in ipair(allEntities) do
    ShapeList.DestroyEntity(entity)
end

-- Destroy every entity (by name)
local allEntities = ShapeList.GetAllEntities()
log("Destroying " .. #(allEntities) .. " ShapeEntities")
for _,entity in ipair(allEntities) do
    ShapeList.DestroyEntity(entity.name)
end

-- Create some data
local data = ShapeData.new()
data.positions = { ... }
data.lines = { ... }

-- Create an instance
local instance = ShapeList.CreateInstance("myInstance")
if instance ~= nil then
    -- Assign the data, and log if there was a problem
    if not instance:SetShapeData(data) then
        log("Failed to set instance shape data")
        instance:Destroy()
    else
        -- Set up the rest of the instance
        instance.translation = ...
    end
end

-- Create some data
local data = ShapeData.new()
data.positions = { ... }
data.lines = { ... }

-- Register the shape
local success = ShapeData.Register("myShape", data)

if success then
    -- Create an instance
    local instance = ShapeList.CreateInstance("myInstance")
    if instance ~= nil then
        -- Assign the shape name
        if not instance:SetShapeDataName("myShape") then
            log("Failed to set instance shape name")
            instance:Destroy()
        else
            -- Set up the rest of the instance
            instance.translation = ...
        end
    end
end

-- Create an instance and set it up
local tmpInstance = ShapeList.CreateInstance("myInstance")
...

-- Set a lifetime for the instance
tickLifetime = 100

Event.Logic.Subscribe("myEvent", function(logicEvent)

    -- Decrease the lifetime
    tickLifetime = tickLifetime - 1

    -- Destroy the instance when the lifetime reaches 0
    if tickLifetime == 0 then
        local instance = ShapeList.GetInstance("myInstance")
        if instance ~= nil then
            instance:Destroy()
        end
    end
end)

-- Create some data
local data = ShapeData.new()
data.positions = { ... }
data.lines = { ... }

-- Create an entity
local entity = ShapeList.CreateEntity("myEntity")
if entity ~= nil then
    -- Assign the data, and log if there was a problem
    if not entity:SetShapeData(data) then
        log("Failed to set entity shape data")
        entity:Destroy()
    else
        -- Set up the rest of the entity
        entity.coordGrid = ...
    end
end

-- Create some data
local data = ShapeData.new()
data.positions = { ... }
data.lines = { ... }

-- Register the shape
local success = ShapeData.Register("myShape", data)

if success then
    -- Create an entity
    local entity = ShapeList.CreateEntity("myEntity")
    if entity ~= nil then
        -- Assign the shape name
        if not entity:SetShapeDataName("myShape") then
            log("Failed to set entity shape name")
            entity:Destroy()
        else
            -- Set up the rest of the entity
            entity.coordGrid = ...
        end
    end
end

-- Create an entity
local entity = ShapeList.CreateEntity("myEntity")
entity:SetShapeDataName("myShape")
entity.coordGrid = CoordGrid._0_50_50_32_32

-- Set the entity to stop drawing when more than 20 tiles from the player
entity:SetDrawDistance(20 * 512) -- 20 tiles, each at 512 fine units

-- Create an entity
local entity = ShapeList.CreateEntity("myEntity")
entity:SetShapeDataName("myShape")
entity.coordGrid = CoordGrid._0_50_50_32_32

-- Set the entity to start fading out at 16 tiles from the player, and
-- have faded out completely at 20 tiles from the player
entity:SetDrawDistance(16 * 512, 20 * 512)

-- Create an entity and set it up
local tmpEntity = ShapeList.CreateEntity("myEntity")
...

-- Set a lifetime for the entity
tickLifetime = 100

Event.Logic.Subscribe("myEvent", function(logicEvent)

    -- Decrease the lifetime
    tickLifetime = tickLifetime - 1

    -- Destroy the entity when the lifetime reaches 0
    if tickLifetime == 0 then
        local entity = ShapeList.GetEntity("myEntity")
        if entity ~= nil then
            entity:Destroy()
        end
    end
end)