Odessey.lua

*No download available for this framework yet.*

Odyssey.lua is a framework that adds the ability to possess enemies like in Super Mario Odyssey. You may customize the possession behavior and much more.

Insallation

To load the API, place this line in your script.

local odyssey = API.load("odyssey")

This API requires a folder called odyssey. The is a required file in this folder must be a PNG file called hat

AI

You may customize the AI of the NPC when it is possessed. This is a list of events that are supported:

Name	Description
onTick	Will get called on every tick call.
onDraw	Will get called on every draw call.
onDeath	Will get called when the NPC dies.
onPossessed	Will get called the first frame the NPC is possesed.
onRevert	Will get called the last frame before the player reverts back.

All of these events must be defined as functions, and each event will pass one parameter, the NPC that is possesed.

Example:

local odyssey = API.load("odyssey")

--The function will get called every tick and will pass *npc* as the NPC object that is being possesed
odyssey.ai[NPC_ID].onTick = function(npc)
  --Here you can customize the AI
end

If an enemy is possessed and it does not find a defined function it will instead use ai[0]. This consists of premade functions. You may customize ai[0] to make generic NPC functions.

Hat

This table holds customizable values and other data for the hat. You can customize the hat by changing some of these values.

odyssey.hat.priority = 0

Name	Type/Default Value	Description
img	LuaImgResource "hat.png" found inside the odyssey folder	The image of the hat.
movement	function The default movement	The movement the hat should have when activated. odyssey.hat.movement = function() --script end
disabled	Boolean false	If set to true, it will prevent the hat from getting activated.
frames	Number 8	The total number of frames.
priority	Number -25	The priority the hat should be drawn at.
speedXIni	Number 6	The initial x-speed of the hat when it is activated. Will automatically flip the number to negative if the player is facing left.
speedYIni	Number 0	The initial y-speed of the hat when it is activated.
speedXMax	Number 7.5	The maximum x-speed of the hat. Will automatically cap negative numbers too (setting speed -8 will turn into -7.5)
speedYMax	Number 4	The maximum y-speed of the hat. Will automatically cap negative numbers too (setting speed -8 will turn into -4)
width	Number 32	The width of the hat.
height	Number 32	The height of the hat.
gfxOffsetX	Number 0	The X offset of the image.
gfxOffsetY	Number 0	The Y offset of the image.
x	Number 0	The X coordinate of the hat.
y	Number 0	The Y coordinate of the hat.
speedX	Number 0	The current x-speed of the hat.
speedY	Number 0	The current y-speed of the hat.
facing	Number 1 (Will either turn to -1[left] or 1[right] when activated. The direction facing will match the direction the player is facing.	The initial direction of the hat when it is activated.
frame	Number 1	The current frame that is being drawn.
frameSpeed	Number 8	The number of frames it should wait until the next frame appears.
animationTimer	Number 0	The timer increments by 1 every frame. When this number reaches the value of frameSpeed, it will reset to 0 and increment frame.
timer	Number 0	The number of frames that have passed since when the hat was activated.

HatNPC

This table holds customizable values and other data for the hat possession effect. This will only be active when posDisplay is set to POSDISPLAY_HAT

odyssey.hatNPC.priority = 0

Name	Type/Default Value	Description
img	LuImgResource The hat-NPC.png file found inside the odyssey folder. If there is no image, then this will be nil.	The image that is used to make the effect. The first part of the image should be framestyle-0, the second part should be framestyle-1 left, and the third part should be framestyle-1 right.
width	Number 32	The width of the image.
height	Number 16	The height of the image.
priority	Number -25	The priority the effect should be drawn at.
frames	Number 1	The number of frames each section has.
frameSpeed	Number 8	The number of frames it should wait until the next frame appears.
gfxOffsetX	Table	A table organized by NPC IDs. You can set an offset per NPC. odyssey.hatNPC.gfxOffsetX[NPC_ID] = number If the frame style of the NPC is set to 1, then it will automatically flip the offset when the NPC faces the other way.
gfxOffsetY	Table	A table organized by NPC IDs. You can set an offset per NPC. odyssey.hatNPC.gfxOffsetY[NPC_ID] = number If the frame style of the NPC is set to 1, then it will automatically flip the offset when the NPC faces the other way.
framestyle	Table	A table organized by NPC IDs. You can set a framestyle per NPC. odyssey.hatNPC.gfxOffsetX[NPC_ID] = number You can set the frame style to be 0 or 1. frame style 0 will make the hat only have one directon, while frame style 1 will flip along with the direction the NPC is facing.
frame	Number 1	The current frame being shown.
animationTimer	Number 0	The timer increments by 1 every frame. When this number reaches the value of frameSpeed, it will reset to 0 and increment frame.

PlayerIMG

This is a table that contains all of the characters images of them in their normal and hatless value.

The structure of the table is as follows:

odyssey.playerIMG[CHARACTER_ID] = {
  -- All of the images featuring the character without his hat
  [0] = {
    [0] = ''LuaImageResource''  -- Death Effect
    [1] = ''LuaImageResource''  -- Powerup 1
    [2] = ''LuaImageResource''  -- Powerup 2 
    ...    
    [n] = ''LuaImageResource''  -- Powerup n
  }
  -- All of the images featuring the character with his hat
  [1] = {
    [0] = ''LuaImageResource''  -- Death Effect
    [1] = ''LuaImageResource''  -- Powerup 1
    [2] = ''LuaImageResource''  -- Powerup 2 
    ...    
    [n] = ''LuaImageResource''  -- Powerup n
  }
}

By default, it will load the player images inside the "Odyssey" folder. File names with an h stand for files that represent the player hatless. For example, placing an image called "mario-1.png" will make mario be that image when he has a hat, and setting an image called "mario-1h.png" will make Mario turn into that image when he activates his hat. If the image is not found inside the folder, it will not swap the player's images. The images supported are all of the powerup files (mario-1.png, luigi-2.png, megaman-1.png), and all of the death effects (3,5,129,130,134,149,150,151,152,153,154,155,156,157,158,159,160,161).

Misc

Name	Type	Description
actionKey	String	Default: altrun The key that will be used to activate the hat, and to stop possessing an enemy. Value must be: up, down, left, right, jump, altjump, run, altrun, dropitem or pause
transformedID	Number	The ID of the NPC that is possessed. Will return 0 if no NPC is being possessed.
activate()	Function	Will activate the hat. Automatically gets called when the player is in the normal state and presses the action key.
deactivate()	Function	Will deactivate the hat. Automatically gets called when the hat makes contact with the player.
transform(npc)	Function	Will force the player to transform into an NPC. The function has one parameter and it must be the NPC object of the NPC you want the transformation on. Automatically gets called when the hat makes contact with an NPC.
revert()	Function	Will turn the player back to normal when he is possessing an NPC. Automatically gets called when pressing the action key while possessing an NPC.

--[[
      If you want to get the possessed NPC directly, you can set up the following:
]]
if odyssey.transformedID ~= 0 then
  for _,v in pairs(NPC.get(odyssey.transformedID)) do
    local npc = pnpc.wrap(v)
    if npc.data.pos then
      -- Script goes here
      break
    end
  end
end