- Game Constants
- Utility
- Styling
- Logging
- Audio
- Game State
- Actor Operations
- Artifact Operations
- Status Effect Operations
- Card Operations
- Damage & Heal
- Player Operations
- Merchant Operations
- Random Utility
- Localization
- Content Registry
General game constants.
DECAY_ALL
Status effect decays by all stacks per turn.
DECAY_NONE
Status effect never decays.
DECAY_ONE
Status effect decays by 1 stack per turn.
GAME_STATE_EVENT
Represents the event game state.
GAME_STATE_FIGHT
Represents the fight game state.
GAME_STATE_GAMEOVER
Represents the game over game state.
GAME_STATE_MERCHANT
Represents the merchant game state.
GAME_STATE_RANDOM
Represents the random game state in which the active story teller will decide what happens next.
PLAYER_ID
Player actor id for use in functions where the guid is needed, for example: deal_damage(PLAYER_ID, enemy_guid, 10).
None
General game constants.
None
fetch
Fetches a value from the persistent store
Signature:
fetch(key : string) -> any
guid
returns a new random guid.
Signature:
guid() -> guid
random
Returns a random number between 0 and 1. Prefer this function over math.random(), as this is seeded for the session.
Signature:
random() -> number
random_int
Returns a random number between min and max. Prefer this function over math.random(), as this is seeded for the session.
Signature:
random_int(min : number, max : number) -> number
store
Stores a persistent value for this run that will be restored after a save load. Can store any lua basic value or table.
Signature:
store(key : string, value : any) -> None
Helper functions for text styling.
None
text_bg
Makes the text background colored. Takes hex values like #ff0000.
Signature:
text_bg(color : string, value : any) -> string
text_bold
Makes the text bold.
Signature:
text_bold(value : any) -> string
text_italic
Makes the text italic.
Signature:
text_italic(value : any) -> string
text_underline
Makes the text underlined.
Signature:
text_underline(value : any) -> string
Various logging functions.
None
log_d
Log at danger level to player log.
Signature:
log_d(value : any) -> None
log_i
Log at information level to player log.
Signature:
log_i(value : any) -> None
log_s
Log at success level to player log.
Signature:
log_s(value : any) -> None
log_w
Log at warning level to player log.
Signature:
log_w(value : any) -> None
print
Log to session log.
Signature:
print(...) -> None
Audio helper functions.
None
play_audio
Plays a sound effect. If you want to play button.mp3 you call play_audio("button").
Signature:
play_audio(sound : string) -> None
play_music
Start a song for the background loop. If you want to play song.mp3 you call play_music("song").
Signature:
play_music(sound : string) -> None
Functions that modify the general game state.
None
get_action_points_per_round
get the number of action points per round.
Signature:
get_action_points_per_round() -> number
get_event_history
Gets the ids of all the encountered events in the order of occurrence.
Signature:
get_event_history() -> string[]
get_fight
Gets the fight state. This contains the player hand, used, exhausted and round information.
Signature:
get_fight() -> fight_state
get_fight_round
Gets the fight round.
Signature:
get_fight_round() -> number
get_stages_cleared
Gets the number of stages cleared.
Signature:
get_stages_cleared() -> number
had_event
Checks if the event happened at least once.
Signature:
had_event(event_id : type_id) -> boolean
had_events
Checks if all the events happened at least once.
Signature:
had_events(event_ids : type_id[]) -> boolean
had_events_any
Checks if any of the events happened at least once.
Signature:
had_events_any(eventIds : string[]) -> boolean
set_action_points_per_round
set the number of action points per round.
Signature:
set_action_points_per_round(points : number) -> None
set_event
Set event by id.
Signature:
set_event(event_id : type_id) -> None
set_fight_description
Set the current fight description. This will be shown on the top right in the game.
Signature:
set_fight_description(desc : string) -> None
set_game_state
Set the current game state. See globals.
Signature:
set_game_state(state : next_game_state) -> None
Functions that modify or access the actors. Actors are either the player or enemies.
None
actor_add_hp
Increases the hp value of a actor by a number. Can be negative value to decrease it. This won't trigger any on_damage callbacks
Signature:
actor_add_hp(guid : guid, amount : number) -> None
actor_add_max_hp
Increases the max hp value of a actor by a number. Can be negative value to decrease it.
Signature:
actor_add_max_hp(guid : guid, amount : number) -> None
actor_set_hp
Sets the hp value of a actor to a number. This won't trigger any on_damage callbacks
Signature:
actor_set_hp(guid : guid, amount : number) -> None
actor_set_max_hp
Sets the max hp value of a actor to a number.
Signature:
actor_set_max_hp(guid : guid, amount : number) -> None
add_actor_by_enemy
Creates a new enemy fighting against the player. Example add_actor_by_enemy("RUST_MITE").
Signature:
add_actor_by_enemy(enemy_guid : type_id) -> string
get_actor
Get a actor by guid.
Signature:
get_actor(guid : guid) -> actor
get_opponent_by_index
Get opponent (actor) by index of a certain actor. get_opponent_by_index(PLAYER_ID, 2) would return the second alive opponent of the player.
Signature:
get_opponent_by_index(guid : guid, index : number) -> actor
get_opponent_count
Get the number of opponents (actors) of a certain actor. get_opponent_count(PLAYER_ID) would return 2 if the player had 2 alive enemies.
Signature:
get_opponent_count(guid : guid) -> number
get_opponent_guids
Get the guids of opponents (actors) of a certain actor. If the player had 2 enemies, get_opponent_guids(PLAYER_ID) would return a table with 2 strings containing the guids of these actors.
Signature:
get_opponent_guids(guid : guid) -> guid[]
get_player
Get the player actor. Equivalent to get_actor(PLAYER_ID)
Signature:
get_player() -> actor
remove_actor
Deletes a actor by id.
Signature:
remove_actor(guid : guid) -> None
Functions that modify or access the artifacts.
None
get_artifact
Returns the artifact definition. Can take either a guid or a typeId. If it's a guid it will fetch the type behind the instance.
Signature:
get_artifact(id : string) -> artifact
get_artifact_instance
Returns the artifact instance by guid.
Signature:
get_artifact_instance(guid : guid) -> artifact_instance
get_artifacts
Returns all the artifacts guids from the given actor.
Signature:
get_artifacts(actor_guid : string) -> guid[]
give_artifact
Gives a actor a artifact. Returns the guid of the newly created artifact.
Signature:
give_artifact(type_id : type_id, actor : guid) -> string
remove_artifact
Removes a artifact.
Signature:
remove_artifact(guid : guid) -> None
Functions that modify or access the status effects.
None
add_status_effect_stacks
Adds to the stack count of a status effect. Negative values are also allowed.
Signature:
add_status_effect_stacks(guid : guid, count : number) -> None
get_actor_status_effects
Returns the guids of all status effects that belong to a actor.
Signature:
get_actor_status_effects(actor_guid : string) -> guid[]
get_status_effect
Returns the status effect definition. Can take either a guid or a typeId. If it's a guid it will fetch the type behind the instance.
Signature:
get_status_effect(id : string) -> status_effect
get_status_effect_instance
Returns the status effect instance.
Signature:
get_status_effect_instance(effect_guid : guid) -> status_effect_instance
give_status_effect
Gives a status effect to a actor. If count is not specified a stack of 1 is applied.
Signature:
give_status_effect(type_id : string, actor_guid : string, (optional) count : number) -> None
remove_status_effect
Removes a status effect.
Signature:
remove_status_effect(guid : guid) -> None
set_status_effect_stacks
Sets the stack count of a status effect by guid.
Signature:
set_status_effect_stacks(guid : guid, count : number) -> None
Functions that modify or access the cards.
None
cast_card
Tries to cast a card with a guid and optional target. If the cast isn't successful returns false.
Signature:
cast_card(card_guid : guid, (optional) target_actor_guid : guid) -> boolean
get_card
Returns the card type definition. Can take either a guid or a typeId. If it's a guid it will fetch the type behind the instance.
Signature:
get_card(id : type_id) -> card
get_card_instance
Returns the instance object of a card.
Signature:
get_card_instance(card_guid : guid) -> card_instance
get_cards
Returns all the card guids from the given actor.
Signature:
get_cards(actor_guid : string) -> guid[]
give_card
Gives a card.
Signature:
give_card(card_type_id : type_id, owner_actor_guid : guid) -> string
remove_card
Removes a card.
Signature:
remove_card(card_guid : string) -> None
upgrade_card
Upgrade a card without paying for it.
Signature:
upgrade_card(card_guid : guid) -> boolean
upgrade_random_card
Upgrade a random card without paying for it.
Signature:
upgrade_random_card(actor_guid : guid) -> boolean
Functions that deal damage or heal.
None
deal_damage
Deal damage from one source to a target. If flat is true the damage can't be modified by status effects or artifacts. Returns the damage that was dealt.
Signature:
deal_damage(source : guid, target : guid, damage : number, (optional) flat : boolean) -> number
deal_damage_card
Deal damage from one source to a target from a card. If flat is true the damage can't be modified by status effects or artifacts. Returns the damage that was dealt.
Signature:
deal_damage_card(source : guid, card : guid, target : guid, damage : number, (optional) flat : boolean) -> number
deal_damage_multi
Deal damage to multiple enemies from one source. If flat is true the damage can't be modified by status effects or artifacts. Returns a array of damages for each actor hit.
Signature:
deal_damage_multi(source : guid, targets : guid[], damage : number, (optional) flat : boolean) -> number[]
heal
Heals the target triggered by the source.
Signature:
heal(source : guid, target : guid, amount : number) -> None
simulate_deal_damage
Simulate damage from a source to a target. If flat is true the damage can't be modified by status effects or artifacts. Returns the damage that would be dealt.
Signature:
simulate_deal_damage(source : guid, target : guid, damage : number, (optional) flat : boolean) -> number
Functions that are related to the player.
None
finish_player_turn
Finishes the player turn.
Signature:
finish_player_turn() -> None
give_player_gold
Gives the player gold.
Signature:
give_player_gold(amount : number) -> None
player_buy_artifact
Let the player buy the artifact with the given id. This will deduct the price form the players gold and return true if the buy was successful.
Signature:
player_buy_artifact(card_id : type_id) -> boolean
player_buy_card
Let the player buy the card with the given id. This will deduct the price form the players gold and return true if the buy was successful.
Signature:
player_buy_card(card_id : type_id) -> boolean
player_draw_card
Let the player draw additional cards for this turn.
Signature:
player_draw_card(amount : number) -> None
player_give_action_points
Gives the player more action points for this turn.
Signature:
player_give_action_points(points : number) -> None
Functions that are related to the merchant.
None
add_merchant_artifact
Adds another random artifact to the merchant
Signature:
add_merchant_artifact() -> None
add_merchant_card
Adds another random card to the merchant
Signature:
add_merchant_card() -> None
get_merchant
Returns the merchant state.
Signature:
get_merchant() -> merchant_state
get_merchant_gold_max
Returns the maximum value of artifacts and cards that the merchant will sell. Good to scale random_card and random_artifact.
Signature:
get_merchant_gold_max() -> number
Functions that help with random generation.
None
gen_face
Generates a random face.
Signature:
gen_face((optional) category : number) -> string
random_artifact
Returns the type id of a random artifact.
Signature:
random_artifact(max_price : number) -> type_id
random_card
Returns the type id of a random card.
Signature:
random_card(max_price : number) -> type_id
Functions that help with localization.
None
l
Returns the localized string for the given key. Examples on locals definition can be found in /assets/locals. Example: l('cards.MY_CARD.name', "English Default Name")
Signature:
l(key : string, (optional) default : string) -> string
These functions are used to define new content in the base game and in mods.
None
delete_base_game
Deletes all base game content. Useful if you don't want to include base game content in your mod.
delete_base_game() -- delete all base game content
delete_base_game("artifact") -- deletes all artifacts
delete_base_game("card") -- deletes all cards
delete_base_game("enemy") -- deletes all enemies
delete_base_game("event") -- deletes all events
delete_base_game("status_effect") -- deletes all status effects
delete_base_game("story_teller") -- deletes all story tellers
Signature:
delete_base_game((optional) type : string) -> None
delete_card
Deletes a card.
delete_card("SOME_CARD")Signature:
delete_card(id : type_id) -> None
delete_enemy
Deletes an enemy.
delete_enemy("SOME_ENEMY")Signature:
delete_enemy(id : type_id) -> None
delete_event
Deletes an event.
delete_event("SOME_EVENT")Signature:
delete_event(id : type_id) -> None
delete_status_effect
Deletes a status effect.
delete_status_effect("SOME_STATUS_EFFECT")Signature:
delete_status_effect(id : type_id) -> None
delete_story_teller
Deletes a story teller.
delete_story_teller("SOME_STORY_TELLER")Signature:
delete_story_teller(id : type_id) -> None
register_artifact
Registers a new artifact.
register_artifact("REPULSION_STONE",
{
name = "Repulsion Stone",
description = "For each damage taken heal for 2",
price = 100,
order = 0,
callbacks = {
on_damage = function(ctx)
if ctx.target == ctx.owner then
heal(ctx.owner, 2)
end
return nil
end,
}
}
)Signature:
register_artifact(id : type_id, definition : artifact) -> None
register_card
Registers a new card.
register_card("MELEE_HIT",
{
name = "Melee Hit",
description = "Use your bare hands to deal 5 (+3 for each upgrade) damage.",
state = function(ctx)
return "Use your bare hands to deal " .. highlight(5 + ctx.level * 3) .. " damage."
end,
max_level = 1,
color = "#2f3e46",
need_target = true,
point_cost = 1,
price = 30,
callbacks = {
on_cast = function(ctx)
deal_damage(ctx.caster, ctx.target, 5 + ctx.level * 3)
return nil
end,
}
}
)Signature:
register_card(id : type_id, definition : card) -> None
register_enemy
Registers a new enemy.
register_enemy("RUST_MITE",
{
name = "Rust Mite",
description = "Loves to eat metal.",
look = "/v\\",
color = "#e6e65a",
initial_hp = 22,
max_hp = 22,
gold = 10,
callbacks = {
on_turn = function(ctx)
if ctx.round % 4 == 0 then
give_status_effect("RITUAL", ctx.guid)
else
deal_damage(ctx.guid, PLAYER_ID, 6)
end
return nil
end
}
}
)Signature:
register_enemy(id : type_id, definition : enemy) -> None
register_event
Registers a new event.
register_event("SOME_EVENT",
{
name = "Event Name",
description = "Flavor Text... Can include **Markdown** Syntax!",
choices = {
{
description = "Go...",
callback = function()
-- If you return nil on_end will decide the next game state
return nil
end
},
{
description = "Other Option",
callback = function() return GAME_STATE_FIGHT end
}
},
on_enter = function()
play_music("energetic_orthogonal_expansions")
give_card("MELEE_HIT", PLAYER_ID)
give_card("MELEE_HIT", PLAYER_ID)
give_card("MELEE_HIT", PLAYER_ID)
give_card("RUPTURE", PLAYER_ID)
give_card("BLOCK", PLAYER_ID)
give_artifact(get_random_artifact_type(150), PLAYER_ID)
end,
on_end = function(choice)
-- Choice will be nil or the index of the choice taken
return GAME_STATE_RANDOM
end,
}
)Signature:
register_event(id : type_id, definition : event) -> None
register_status_effect
Registers a new status effect.
register_status_effect("BLOCK", {
name = "Block",
description = "Decreases incoming damage for each stack",
look = "Blk",
foreground = "#219ebc",
state = function(ctx)
return "Takes " .. highlight(ctx.stacks) .. " less damage"
end,
can_stack = true,
decay = DECAY_ALL,
rounds = 1,
order = 100,
callbacks = {
on_damage_calc = function(ctx)
if ctx.target == ctx.owner then
add_status_effect_stacks(ctx.guid, -ctx.damage)
return ctx.damage - ctx.stacks
end
return ctx.damage
end
}
})Signature:
register_status_effect(id : type_id, definition : status_effect) -> None
register_story_teller
Registers a new story teller.
register_story_teller("STORY_TELLER_XYZ", {
active = function(ctx)
if not had_events_any({ "A", "B", "C" }) then
return 1
end
return 0
end,
decide = function(ctx)
local stage = get_stages_cleared()
if stage >= 3 then
set_event("SOME_EVENT")
return GAME_STATE_EVENT
end
-- Fight against rust mites or clean bots
local d = math.random(2)
if d == 1 then
add_actor_by_enemy("RUST_MITE")
elseif d == 2 then
add_actor_by_enemy("CLEAN_BOT")
end
return GAME_STATE_FIGHT
end
})Signature:
register_story_teller(id : type_id, definition : story_teller) -> None