ezlibs

Installation

copy / clone ezlibs-scripts into server/scripts/ezlibs-scripts
copy / clone ezlibs-assets into server/assets/ezlibs-assets
create these folders
- server/memory/area/
- server/memory/player/
- server/encounters/
- server/scripts/events/

ezwarps

Automatically adds landings locations for server warps to your server, also handles arrival / leaving animations

Supported warp types:

Server Warp
- supports arrival animations
Custom Warp
- supports arrival animations
Interact Warp
- (a warp activated by interaction)
- supports arrival animations
- supports landing animations
Radius Warp
- (a warp activated by entering its radius)
- supports arrival animations
- supports landing animations

Supported warp custom properties:

Incoming Data (string) secret to share with the server that is linking to you; for their Data
Warp In (boolean) should the warp in animation be shown (laser from sky)
Warp Out (boolean) should the warp out animation be shown (laser from sky)
Arrival Animation (string) name of special animation which should play on warp in
Leave Animation (string) name of special animation to play on warp out
Dont Teleport (boolean) add this property if you just want the warp to animate, no teleporting

custom properties for warping to another server:

Address (string) Ip address / hostname of server
Data (string) unique string pre shared with the server so that the server can decide where transfered players should appear

custom properties for warping to another map:

Target Area (string) name of area you want to transfer to, (same as filename, minus the .tmx)
Target Object (string/object) id of object you want to teleport to

Radius Warp only:

Activation Radius (float) the warp will activate when a player enters this radius

Special Animations (for arrival / leave animation):

fall_in
lev_beast_in
lev_beast_out
arrow_up_left_out
arrow_up_right_out
arrow_down_left_out
arrow_down_right_out
arrow_up_left_in
arrow_up_right_in
arrow_down_left_in
arrow_down_right_in
fall_off_2
log_in
log_out

Usage Examples

Making "Arrow Warps" using Radius Warp

Arrow A

Arrow B

More special animations can be added by requiring them in main.lua -> special_animations

eznpcs

Automatically creates NPC's for your server based on objects you add to the map in Tiled.

You can create branching dialogue trees for conversations with NPCs all from the map editor, and if you want you can add scripted events for more complicated interactions.

You can create paths using waypoints in the map editor which the NPCs will follow, with optional wait times and random path selection.

Setup

add objects to your map with Type=NPC on an object layer above the tile layer where you want the NPC to spawn.

NPC Type

Custom properties:

Asset Name string
- name of npc tilesheet from yourserver/assets/ezlibs-assets/eznpcs/sheet
- for example heel-navi-exe4_black (no file extension)
Direction string
- see the section on Directions.
Dialogue Type string
- by including this property, this npc will become interactable
- see the section on Dialogues.
- all the other dialogue properties can also be used here
Next Waypoint 1 object
- by including this property, this npc will follow waypoints
- Indicates the first waypoint that the npc should move to
- see the section on Waypoints

Dialogues

any object can be a dialogue, you can use these custom properties to define what will happen next in the conversation when the dialogue is reached Custom properties:

Dialogue Type string
- first
  - this dialogue will make the NPC say the first Text # custom property, usually Text 1
  - after Text 1 is finished,
- random
  - this dialogue will choose a random Text # custom property to say, it might be Text 1, Text 2, Text 5, etc.
  - If there is a Next # property with a matching number, that dialogue will be triggered next, otherwise it will default to Next 1
- question
  - prompts the player to choose yes or no, with Text 1 as the prompt text
  - afterwards the dialogues Next 1 or Next 2 will be triggered, matching the player's choice.
- quiz
  - presents up to 3 options based on Text 1, Text 2, and Text 3
  - afterwards the dialogues Next 1, Next 2, or Next 3 will be triggered, matching the player's choice.
- before
  - compares current time against Date custom property
  - if the current time is before Date, Text 1 will be displayed, otherwise Text 2, it will go to the respective Next x dialogue node afterwards
- after
  - same as before, checks if current time is after Date
- shop
  - will open a shop where the player can buy items
  - add items to the shop with Item #(object) custom properties
    - item objects can have these properties Items
  - after the shop is closed the first Next # dialogue will be triggered
- item
  - gives the player an item
  - specify items to be gifted Item #(object) custom properties
    - item objects can have these properties Items
  - by default a textbox will be sent saying "Got x Item", you can disable this with Dont Notify bool (*default is false)
- itemcheck
  - checks if the player has the required items, Next 1 will be triggered if requirements are met, otherwise Next 2 will be triggered
  - if the Take Item custom property is set to true, all the required items will be taken from the player
  - specify item requirements with Item #(object) custom properties
    - item objects can have these properties Items
- password
  - prompts the user for an input, if it matches the Text 1 custom property, go to Next 1 dialouge, otherwise go to Next 2 dialogue
- none
  - usually used with Event Name, no dialogue, but the event will still be triggered
Text 1 string
- (numbered, you can also include, 2, 3, 4 etc. up to 10)
- Text that will be spoken by NPCS who have this dialogue
Next 1 object
- (numbered, you can also include, 2, 3, 4 etc. up to 10)
- ID of the next dialogue to activate after the corresponding Text is spoken / chosen
Event Name string
- Name of event to activate when this dialogue starts, events can be added in your eznpcs entry script, see Dialogue Events for details.
Mugshot string
- Override the speaking bot's mugshot with another one for this dialogue node.
- for example, even though prog is speaking, we can make it display Bass' mugshot by setting Mugshot to bass
- There is a special value player which will get the mugshot of the player talking to the NPC, useful for back and forth conversations

Items

Name string
Description string (default is ???)
Type string
- item (default)
- money
- keyitem
Price int (default is 9999999), only used for shops
Amount int (default is 1), not used by shops

Waypoints

any object can be a waypoint, you can use these custom properties to define what the NPC will do once it reaches said object. Custom properties:

Waypoint Type string
- first
  - after reaching this waypoint, the NPC will head to the waypoint referenced by the first Next Waypoint # custom property, usually Next Waypoint 1
- random
  - after reaching this waypoint, the next one will be selected from a random Next Waypoint # custom property.
- before
  - compares current time against Date custom property
  - if the current time is before Date, Next Waypoint 1 will be next, otherwise Next Waypoint 2 will be.
- after
  - same as before, checks if current time is after Date
Wait Time number
- time in seconds to wait before moving to next waypoint
Direction string
- direction to face while waiting
- see the section on Directions.
Waypoint Event string
- coming soon

Date

the Date custom property can be used for time based conditions on Dialogue nodes and Waypoints the format is a super duper basic cron like format. there are 6 numbers seperated by spaces for each part of the date string

second minute hour day month year

you can hardcode a specific date and time like this:

0 0 13 1 1 2000 (1pm on first of january year 2000)

or you can use wildcards which will always behave as the current time for that column

30 * * * * * (30 seconds through the current minute, today)

Interact Relay

any object with the custom property Interact Relay (object) that is interacted with will start a conversation with the NPC that it is referencing
useful for starting conversations with NPCS that are behind objects like counters

DialogueEvents

you can add custom logic for dialogues using eznpcs.add_event(event_object)
dialogue events must return promises, see the example
eznpcs will automatically try and load the file /server/scripts/events/eznpcs_events.lua for this purpose, so create that file and add events from there
loaded events will activated when a player reaches a dialogue during a conversation with a matching Event Name custom property
the action of the event is a callback which allows for any and all custom interactions.
callback parameters:
- npc table
  - information about the NPC who the player is conversing with
- player_id string
  - id of the player who engaged the npc in conversation
- dialogue table
  - information about the dialogue object
- relay_object table
  - information about the relay object which the player started their conversation with the NPC through
  - nil if the player did not start conversing using a relay object
expected return types
- nil
  - will end the conversation
- number
  - id of the next dialogue object that you want to trigger after this, usually get it from a custom property on the current dialogue object.

Here is an example dialogue event where a sound effect plays and the player enjoys gravy

local eznpcs = require('scripts/ezlibs-scripts/eznpcs/eznpcs')
local sfx = {
    recover='/server/assets/ezlibs-assets/sfx/recover.ogg',
}
local some_event = {
    name = "Drink Gravy",
    action = function(npc, player_id, dialogue, relay_object)
        return async(function()
            local player_mugshot = Net.get_player_mugshot(player_id)
            Net.play_sound_for_player(player_id, sfx.recover)
            Net.message_player(player_id, "\x01...\x01mmm gravy yum", player_mugshot.texture_path, player_mugshot.animation_path)
            return dialogue.custom_properties["Next 1"]
        end)
    end
}
eznpcs.add_event(some_event)

if you add this example to /server/scripts/events/eznpcs_events.lua you should see it load when you start the server

Waypoint Events

coming soon

Misc

Directions

Left
Right
Up
Down
Up Left
Up Right
Down Left
Down Right

ezmystery

lets you place mystery data objects on your maps to give players key items and money

Setup

add objects to your map with Type=Mystery Datum on an object layer above the tile layer where you want the Mystery data to spawn

Randomizing Spawns

you can specify the minimum and maximum number of green data that you wish to spawn on any given map by adding these properties to your map. By default this behaviour is disabled unless you specify a valid minimum and maximum

Mystery Data Minimum (number)
- minimum number of green data that you wish to appear per jack in.
Mystery Data Maximum (number)
- maximum number of green data that you wish to appear per jack in.

Mystery Dataum

Custom properties:

Type string
- one of these three options
  - money
  - keyitem
  - random
Amount number
- the amount of money to give the player
Name string
- name of the key item to give the player (the item will be created automatically by ezmystery if it does not exist)
Description string
- description of the key item to give the player, if keyitems with the same name already exist, all of them will be updated with the new description
Next #: object
- You can have up to 9 of these, named Next 1, Next 2 etc
- if using the random type, the reward will be selected from a Mystery Option type object; randomly selected from a Next # property

Mystery Option

Custom properties:

(all the same properties as mystery datum, but these are exclusively for providing random rewards as they will be removed from the map when the server loads)

ezmemory

provides easyish saving and loading of things, this library is only interacted with through lua

you can clear all information stored by ezmemory by deleting the files in the /server/memory/ folder that we created during setup

as long as you use the ezmemory functions (as opposed to the built in equivilants) ezmemory will automatically persist player money, items, key items, and any other table data you want.

note that if you create an item which is not a key item, it will not show up anywhere, this can still be useful for your own custom scripts.

local new_item_id = ezmemory.create_or_update_item(item_name,item_description,is_key)

if an item with is_key is given to a player it will show in keyitems
if an item with the same name already exists; the details will be updated, this wont update in the players key items until the player reconnects

local new_item_count = ezmemory.give_player_item(player_id, item_name, amount)

will return nil if the item you attempted to give the player has not been created using ezmemory.create_or_update_item

local item_count = ezmemory.count_player_item(player_id, item_name)

ezmemory.set_player_money(player_id, money)

local success = ezmemory.spend_player_money(player_id, amount)

spends the specified amount of money if the player has enough
returns true if the player had enough money, otherwise returns false

these have been the main functions, but there are more to see in the ezmemory.lua file

ezencounters

handle enemy encounters, and trigger random ones from a table for each map

create a lua file for each map with the same name as the tiled map (default.lua for example) and put the file into the server/encounters/ (create this folder if it does not exist)

encounter options:

name (string)
- if provided, this name can be used to trigger encounters by name, the encounter still needs to be added to a encounter table
path (string)
- path to the main encounter file, usually this will be the same as in the examples, but if you want to create your own .zip you can specify it here, note you will need to copy/modify the code from the provided ezencounters.zip
weight (number)
- relative chance of this particular encounter being picked from table for this area, if one encounter has weight 10 and another has weight 20, the weight 20 one is twice as likely to be picked.
enemies (table)
- ordered list of all the enemies you want to include in the battle
- ranks key
  - 1 v1
  - 2 v2
  - 3 v3
  - 4 sp
  - 5 ex
  - 6 rare1
  - 7 rare2
  - 8 nightmare
- here are all the mobs and available ranks included by default in ezencounters.zip
  - Mettaur (1,2,3,4,6,7)
  - Champy (1,2)
  - Chimpy (1) ~thanks jamesking#9809
  - Chumpy (1) ~thanks jamesking#9809
  - RareChampy (1) ~thanks jamesking#9809
  - Gunner (1,4,6,7)
  - Shooter (1,4)
  - Sniper (1)
  - BigBrute (1)
  - Cactikil (1,5) ~Author Konstinople#7692
  - Cactroll (1,5) ~Author Konstinople#7692
  - Cacter (1,5) ~Author Konstinople#7692
  - Powie (1,5) ~Author Konstinople#7692
  - Powie2 (1,5) ~Author Konstinople#7692
  - Powie3 (1,5) ~Author Konstinople#7692
  - Spikey (1,2,3) ~Author DawnOwl#5358
  - Canodumb (1,2,3) ~Author Konstinople#7692
  - Canosmart (1) ~Author DawnOwl#5358
  - Volgear (1,2,3,4) ~Author LouisE#9864
  - KillerEye (1,2,6,7) ~Author LouisE#9864
  - DemonEye (1) ~Author LouisE#9864
  - JokerEye (1) ~Author LouisE#9864
  - HauntedCandle (1,2,3,4,6,7) ~Author LouisE#9864
  - Fishy (1,2,3,4) ~Author LouisE#9864
  - BombCorn (1,4,6,7) ~Author LouisE#9864
  - JokerEye (1) ~Author LouisE#9864
  - MegaCorn (1) ~Author LouisE#9864
  - GigaCorn (1) ~Author LouisE#9864
  - Bladia (1) ~Author DawnOwl#5358
  - Metrid (1,2,3,4) ~Author DawnOwl#5358
  - Basher (1) ~Author DawnOwl#5358
  - FighterPlane (1,2,3,4) ~Author DawnOwl#5358
  - Catack (1,2,3,4) ~Author DawnOwl#5358
  - Ratty (1,2,3,4) ~Author DawnOwl#5358
positions (grid)
- where to spawn each enemy, 0 = no enemy, to spawn an enemy use the index of the enemy you listed in the enemies table you provided (1 = enemy at index 1 in your enemies table)
tiles (grid)
- defaults to all normal panels

normal
cracked
broken
up
down
left
right
empty
grass
hidden
holy
ice
lava
poison
volcano

teams (grid)
- defaults to the usual battle field

neutral team
blue team
red team

obstacles (table)
- ordered list of all the obstacles you want to include
- here are the included obstacles
  - RockCube
  - Rock
  - Coffin
  - BlastCube
  - IceCube
  - MysteryData
obstacle_positions(table)
- like enemy_positions, but for obstacles
player_positions(table)
- like enemy_positions, but for players.
freedom_mission(table)
- turns (number)
- can_flip (boolean)
music (table)
- path (string), included options:
  - bcc_battle_xg.mid
  - bcc_battle.mid
  - bn1_battle_xg.mid
  - bn1_battle.mid
  - bn1_boss_xg.mid
  - bn1_boss.mid
  - bn2_battle.mid
  - bn2_boss.mid
  - bn3_battle.mid
  - bn3_boss.mid
  - bn3_tournament.mid
  - bn4_battle.mid
  - bn4_boss.mid
  - bn4_tournament.mid
  - bn5_battle_xg.mid
  - bn5_battle.mid
  - bn5_boss_xg.mid
  - bn5_boss.mid
  - bn6_battle_xg.mid
  - bn6_battle.mid
  - bn6_boss_xg.mid
  - bn6_boss.mid
  - bn45_battle_xg.mid
  - bn45_tournament_final.mid

here is an example of the contents, in this case just one potential encounter layout with some mettaurs and a champy

local encounter1 = {
    path="/server/assets/ezlibs-assets/ezencounters/ezencounters.zip",
    weight=10,
    enemies = {
        {name="Mettaur",rank=1},
        {name="Champy",rank=1},
    },
    positions = {
        {0,0,0,0,0,2},
        {0,0,0,0,1,0},
        {0,0,0,1,0,0}
    },
    results_callback = give_result_awards --function (player_id,encounter_info,stats)
}

return {
    minimum_steps_before_encounter=400,
    encounter_chance_per_step=0.01,
    encounters={encounter1}
}

here is another example with every optional field included

local encounter1 = {
    name="example encounter"
    path="/server/assets/ezlibs-assets/ezencounters/ezencounters.zip",
    weight=10,
    enemies = {
        {name="BigBrute",rank=1,max_hp=500,starting_hp=500,nickname="Doggie"},
        {name="Gunner",rank=1},
    },
    positions = {
        {0,0,0,0,0,2},
        {0,0,0,0,1,0},
        {0,0,0,0,0,2}
    },
    tiles = {
        {1,1,9,9,1,1},
        {1,1,9,9,1,1},
        {1,1,9,9,1,1}
    },
    teams = {
        {2,2,0,0,1,1},
        {2,2,0,0,1,1},
        {2,2,0,0,1,1}
    },
    obstacles = {
        {name="RockCube"},
    },
    obstacle_positions = {
        {0,0,1,1,0,0},
        {0,0,1,1,0,0},
        {0,0,1,1,0,0}
    },
    player_positions = {
        {0,0,0,0,0,0},
        {1,0,0,0,0,0},
        {0,0,0,0,0,0}
    },
    freedom_mission={
        turn_count=5,
        player_can_flip=true
    },
    music={
        path="bcc_battle.mid"
    }
}

return {
    minimum_steps_before_encounter=50,
    encounter_chance_per_step=0.1,
    encounters={encounter1}
}

you can also specify a results calback (as seen above) which will be called at the end of the battle; here we are requiring ezmemory in order to give the player some reward monies for winning the battle

local ezmemory = require('scripts/ezlibs-scripts/ezmemory')

local sfx = {
    item_get='/server/assets/ezlibs-assets/sfx/item_get.ogg'
}

local give_result_awards = function (player_id,encounter_info,stats)
    -- stats = { health: number, score: number, time: number, ran: bool, emotion: number, turns: number, npcs: { id: String, health: number }[] }
    -- set the player emotion if they left the battle with full sync (1)
    if stats.emotion == 1 then
        Net.set_player_emotion(player_id, stats.emotion)
    else
        Net.set_player_emotion(player_id, 0)
    end
    -- set the player health to whatever they finished the battle with
    Net.set_player_health(player_id,stats.health)
    if stats.ran then
        return -- no rewards for wimps
    end
    local reward_monies = (stats.score*50)
    ezmemory.spend_player_money(player_id,-reward_monies) -- spending money backwards gives money
    Net.message_player(player_id,"Got $"..reward_monies.."!")
    Net.play_sound_for_player(player_id,sfx.item_get)
end

Radius Encounters

You can create an object with type Radius Encounter which will trigger an encounter the first time a player reaches it. Custom Properties:

Name (string) name of the encounter (from encounter table) to activate
Path (string) if name is not specified, you can trigger an encounter with a mob package zip by specifying it's path
Once (boolean) if true, this encounter will never appear again for this player after they beat it

ezweather

lets you control the weather per map

Setup

add some extra properties to your map file if you want to

ezweather.start_rain_in_area(area_id)

if you specify a Rain Song custom property on your map, it will play while it is raining

ezweather.start_snow_in_area(area_id)

if you specify a Snow Song custom property on your map, it will play while it is snowing

ezweather.clear_weather_in_area(area_id)

restores the original foreground and Song

ezfarms

a large plugin which adds a harvest moon style farming system to your server. but it is a pain to set up so disable it by removing it from the start of main.lua (and the plugin list in main.lua)

custom plugin

If you need to add your own logic that interacts with ezlibs outside of dialogue events / encounter results - create this file /server/scripts/ezlibs-custom/custom.lua and you can add your own custom plugin which will be automatically added by ezlibs main

local ezmemory = require('scripts/ezlibs-scripts/ezmemory')

local custom = {}

custom.on_tick = function (dt)
    print('custom plugin!')
end

return custom

TheMaverickProgrammer / ezlibs-scripts

ezlibs

Installation

Contents

ezwarps

Usage Examples

Making "Arrow Warps" using Radius Warp

eznpcs

Setup

NPC Type

Dialogues

Items

Waypoints

Date

Interact Relay

DialogueEvents

Waypoint Events

Misc

Directions

ezmystery

Setup

Randomizing Spawns

Mystery Dataum

Mystery Option

ezmemory

ezencounters

Radius Encounters

ezweather

Setup

ezfarms

custom plugin

About

Languages