Frameset
Bringing images to life
- Martin
- 7 min read
Processing
At the moment the game is built using Photoshop. I did this with the idea in mind that I wanted to use a simple editor that converts everything to the game using the .psd file. This contains what I call a ‘Scene’, for example the living room. Each layer in Photoshop is equal to a Frameset in the game.
The .psd file is processed with NodeJs and Python so that they become separate transparent images and I have the contours of the images (polygon). The images are then processed with TexturePacker, so that loading into the game is fast.
This is also called an AtlasLoader, only I adjust the json that TexturePacker creates with extra data, such as the polygon info.
{
"meta": {
"ukey": 20,
"height": 240,
"width": 800,
"pathFindingTop": 140,
"audiosets": [
"assets/audio/character/11/en/audio.mp"
],
"image": "assets/scene/20/atlas.png"
},
"layers": [
{
"name": "background-stone-circle",
"frames": [
{
"visible": true,
"quad": {
"x": 1596,
"y": 369,
"w": 198,
"h": 105
},
"x": 82,
"y": 59,
"order": 1,
"collidable": []
}
],
"collidableA": [
1,
2,
3,
4
],
"collidableB": [
4
],
"collidableRect": [
82,
59,
279,
163
],
"zindexStatic": 13,
"zindexType": "static"
},
...
Zindex
The atlas.json extension also includes the zindex, which is a number at which the layer is positioned in Photoshop. This way, the images will all be in the same order on top of each other.
The zindex is even more important than you might think, because it determines whether an entity will walk in front of or behind an object.
This is a number of how high/low the image should be in the game, this is the same as the Photoshop layer order.
I still have to refactor this, but it does exactly what I want at the moment. If the player’s feet are at the same height as the other entity, the zindex in the game will automatically change. I also define whether something has a ‘static’ zindex, or whether it should be ‘above’ another entity.
function World:updateZindex()
local framesetSortByY = {}
for i = 1, #self.framesetsToProcess do
if self.framesetsToProcess[i] and self.framesetsToProcess[i].parentEntity then
local y = self.framesetsToProcess[i]:getY() or self.framesetsToProcess[i]:getFrameY()
if self.framesetsToProcess[i]:getOriginY() ~= Offset.BOTTOM then
-- @warning we use the max height, not the current frame height, but it is oke
y = y + self.framesetsToProcess[i]:calcFrameMaxHeight()
end
-- special cases
if self.framesetsToProcess[i].zindexType == "static" then
local zindexStatic = self.framesetsToProcess[i].zindexStatic
if zindexStatic ~= nil then
-- force the static zindex to be the given number, don't change it
y = tonumber(zindexStatic)
else
-- @warning we assume that the zindex are in correct order inside the yml files
y = i
end
end
-- temp processing table
table.insert(
framesetSortByY,
{
frameset = self.framesetsToProcess[i],
y = y,
ukey = self.framesetsToProcess[i].parentEntity.ukey
}
)
end
end
-- special cases, after processing
for i = 1, #framesetSortByY do
if framesetSortByY[i].frameset.zindexType == "above" then
-- search this frameset
for i2 = 1, #framesetSortByY do
if framesetSortByY[i].frameset.zindexStatic == framesetSortByY[i2].ukey then
framesetSortByY[i].y = framesetSortByY[i2].y + 1
break
end
end
end
end
-- sort using the calculate y
table.sort(
framesetSortByY,
function(a, b)
return a.y ~= nil and b.y ~= nil and a.y < b.y
end
)
-- now we loop over the this sorted by y and create the new zindex
for i = 1, #framesetSortByY do
framesetSortByY[i].frameset.zindex = i
end
-- now we let the engine do his thing with zindex sorting
World.super.updateZindex(self)
end
Frameset
But this article was actually about what exactly a Frameset is in engine3. This is a class in which you can place 1 or more images. If there are more, you can play it like an animation. An entity can have 1 or more Framesets. All essential information about the image is in the Frameset, and is also editable during the game.
A brief overview of the Frameset class
---@class Frameset: Object
---@field parentEntity Object The parent entity that going to use this frameset
---@field namespace string For example scene/item/character
---@field name string
---@field visible boolean
---@field config Config
---@field resource love.Image resource A reference to the atlas image
---@field resourceFile string resourceFile Resource path
---@field frames table<Frame> frames A static image contains only one frame
---@field framekey number Current frame key, a non animation have only one 1 frame. (default 1)
---@field isAnimation boolean It is counting the number of frames > 1
---@field zindex integer The z-index order
---@field scaleX? number Scale. A negative scaling factor to flip about its centerline.
---@field scaleY? number Scale. A negative scaling factor to flip about its centerline.
---@field quad? table<love.Quad> quad Default not loaded
---@field x? integer The x position for the full frameset, to overrule the default Frame.x
---@field y? integer The y position for the full frameset, to overrule the default Frame.y
---@field frameMaxWidth? integer The max width from all the frames in a frameset this is only set after calling self:calcFrameMaxWidth()
---@field frameMaxHeight? integer The max height from all the frames in a frameset this is only set after calling self:calcFrameMaxHeight()
---@field frameMaxWidthObj Frame The frame from all the frames in a frameset this is only set after calling self:calcFrameMaxWidth()
---@field frameMaxHeightObj? Frame The frame from all the frames in a frameset this is only set after calling self:calcFrameMaxHeight()
---@field time? integer Animation timer
---@field animationStatus? number See constants IDLE|PLAYING|PAUSE
---@field callbackAfterDraw? table<function> Table with 0 or more callback functions.
---@field callbackAfterUpdate? table<function> Table with 0 or more callback functions.
---@field callbackAfterXy? table<function> Table with 0 or more callback functions.
---@field callbackAfterVisibility? table<function> Table with 0 or more callback functions.
---@field collidableA? table If this frameset is collidable (sides) {1[opt](left),2([opt]right),3([opt]top),4([opt]bottom)}.
---@field collidableB? table If this frameset is collidable (sides) overrule the other collidable target option {1[opt](left),2([opt]right),3([opt]top),4([opt]bottom)}.
---@field collidableRects? table Collidable rects [{x1,y1,x2,y2}, ...]
---@field whitespace? boolean If the source image uses a whitespace around its image
---@field originX? integer Default the x coordinate origin is Offset.LEFT. For example when you use center, the x position is in the frameset center
---@field originY? integer
---@field callback Callback
...
function Frameset:getOriginY()
return self.originY
end
function Frameset:getOriginX()
return self.originX
end
function Frameset:getZindex()
return self.zindex
end
function Frameset:getFrameX()
local currentFrame = self:getCurrentFrame()
return currentFrame.x
end
function Frameset:getFrameX()
local currentFrame = self:getCurrentFrame()
return currentFrame.x
end
function Frameset:getX()
return self.x
end
function Frameset:getFrameY()
local currentFrame = self:getCurrentFrame()
return currentFrame.y
end
function Frameset:getY()
return self.y
end
function Frameset:stop()
self.animationStatus = self.IDLE
self.framekey = 1
self:hide()
end
--- Start the frameset animation.
-- When you start a animation it will visible.
-- time to show, framekey
-- {
-- {0.00, 1},
-- {0.46, 2},
-- {0.95, 5},
-- ...
-- }
---@param timeTable? table Play the tables like the table
---@param timeTableEndCallback? table When the last key is played
---@param ignoreAutoShow? bool Don't execute the show() function
function Frameset:play(timeTable, timeTableEndCallback, ignoreAutoShow)
if timeTable then
self.timeTable = timeTable
for _, date in pairs(timeTable) do
Tick.delay(
function()
self.framekey = date[2]
-- the last key
if self.timeTable[#self.timeTable][1] == date[1] then
if timeTableEndCallback then
timeTableEndCallback()
end
end
end,
date[1]
)
end
end
self.animationStatus = self.PLAYING
if ignoreAutoShow ~= true then
self:show()
end
end
function Frameset:pause(frameKey)
if frameKey ~= nil then
self.framekey = frameKey
self.frames[self.framekey].visible = true
end
self.animationStatus = self.PAUSE
end
function Frameset:update(dt, entity)
local currentFrame = self:getCurrentFrame()
local update = true
-- its not not visible on the screen
if currentFrame.visible == false then
update = false
end
-- its a static image, no need to update things
if self.isAnimation == false then
update = false
end
-- We don't want to play this animation
if self.isAnimation and self.animationStatus ~= self.PLAYING then
update = false
end
-- We manage our own frame time
if self.timeTable ~= nil then
update = false
end
if update then
self.time = self.time + dt
if self.time >= (currentFrame.duration / 1000) then
self.framekey = (self.framekey % #self.frames) + 1
self.time = 0
end
end
self:callback(self.callbackAfterUpdate, entity, self, update, currentFrame, dt)
return update
end
...
The class itself now contains +/- 866 lines and is too much to post here. This only contains the basis for controlling the images, both animation and static.
Animation
When a frameset has multiple images, it is possible to play them one after the other.
frameset:play()
Martin loop naar rechts
