Odessey.lua

*No download available for this framework yet. There is no page that links here, so congrats for finding this, I guess?*

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.

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(npc, playerObj)	Will get called on every tick call.
onDraw(npc, playerObj)	Will get called on every draw call.
onDeath(npc, playerObj, deathEventObj, deathReason)	Will get called when the NPC dies.
onPossessed(npc, playerObj)	Will get called the first frame the NPC is possessed.
onRevert(npc, playerObj)	Will get called the last frame before the player reverts back.
onHatContact(npc, playerObj, hat)	Will get called when an active hat makes contact with an NPC.

Aside from being able to organize the AI with NPC's IDs, there are also two special indexes that are avalable.

Name	Description
ai[0]	Every NPC will use the values of ai[0] if it does not find a function for its ID.
ai[-1]	Will affect every NPC no matter the circumstance.

Example:

local odyssey = API.load("odyssey")

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

--If an NPC does not have an "onDraw" ai set up. It will default to ai[0].
odyssey.ai[0].onDraw = function(npc, playerObj)
  --Here you can customize the AI
end

--The index "-1" is global and will affect every NPC.
odyssey.ai[-1].onPossesed = function(npc, playerObj)
  --Here you can customize the AI
end

Hat

'Hat' is NPC-700. The framework lets you customize data set by the framework.

odyssey.hat.disabled= true

Name	Type/Default Value	Description
id	double 700	The NPC ID of the hat.
disabled	boolean false	When set to true, it will stop the creation of new hats.
movement	function The default movement.	A function that will get called every tick whose purpose is to control the hat's movement. odyssey.hat.movement = function(hat) -- The function passes one parameter, the NPC object of the hat. --Here you can customize the movement end

Aside from those value, each NPC object will have some value accessible through pnpc.

Name	Description
facing	The direction (-1 or 1) the player was facing when the hat was created.
timer	The amount of frames the NPC has existed.
player	The player object that created the hat.
pos	The player id that is possesing the NPC. This value will be "nil" if it is not being possesed. </syntaxhighlight>

HatNPC

This table holds customizable values and other data for the hat possession effect.

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.
disabled	Boolean false	If set to true, it will stop drawing the hat.
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 upon.
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 direction.
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 direction.
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 one of the following: -1: No hat should be drawn 0: The hat will face one direction 1: The hat will face two directions, left and right.
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.

Ribbon

ribbon table A table filled wih functions that return ribbons.

local particles = API.load("particles")
odyssey.hat.ribbon[CHARACTER_MARIO] = function() --The particle that the hat should throw when it is thrown by Mario. 
  return particles.Ribbon(0, 0, Misc.resolveFile("particles/r_trail.ini"))
end

|}

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	Table	A table organized by player indexes that contains the ID of the NPC that is possessed. Will return 0 if no NPC is being possessed.
newHat(playerObj)	Function	Will create a new hat. Automatically gets called when the player is in the normal state and presses the action key.
transform(npc, playeObj)	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(playeObj)	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.