- Trigger API Reference\DCEI Functions\General
- Texture
- WildCastleDownloadRemoteImages
- Actor
- Unit
- SimpleUnit
- Stats
- Effect
- Behavior
- Sound
- Tag
- Upgrade
- Font
- Ability
- Weapon
- Particle
- SetScreenSleep
- GetGameTime
- SetSimpleUnitMapBounds
- GetValueFromDataPath
- ValidateDataPath
- TriggerAddSimulationCommandEvent
- SendSimulationCommand
- TriggerAddPresentationCommandEvent
- SendPresentationCommand
- ShareDataWithPresentation
- GetSharedDataFromSimulation
- TriggerAddUpdateEvent
- CreateCustomIapProductData
- CreateCustomIapProduct
- AddCustomIapProduct
- GetProtectedValue
- ClearProtectedValue
- SetProtectedValue
- SetEffectFieldValueForPlayer
- ApplyModifier
- IsPointOnNavMesh
- GetClosestPointOnNavMesh
- AddNavmeshCut
- SetPropVisibility
- EnableNavmeshCut
- SetSpeedTurbo
- GetDataContextValue
- GetCardDamageStats
- ResetCardDamageStats
- TriggerOnFocusChange
- GarbageCollect
- GetLuaMemorySize
- GetLevelDataLoadingTime
- Wait
Trigger API Reference\DCEI Functions\General
string Texture(string texture)
string Texture(string texture)
Description
Register a used sprite. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
texture
the sprite name to register.
Example Usage
local image_name = DCEI.Texture("btn_close")
local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameImage(frame, image_name)
void WildCastleDownloadRemoteImages(int projectId, List<string> remoteImages, TypedCallback<List\ callback)
void WildCastleDownloadRemoteImages(int projectId, List<string> remoteImages, TypedCallback<List<string>> callback)
Description
Register remote images that uploaded to platform site under the "Remote Images" field of the "Request Build" section of your project management page. Only supports .png files. Image name will be the key, which must be unique. Cannot delete images uploaded.
Parameters
- int
projectId
the id of the project that uploaded remote images. (id can be found in project page url) - List<string>
remoteImages
list of image names without .png extension. - TypedCallback<List<string>>
callback
When remote images finish loading, this function will be called with a parameter, which is a list of all successfully loaded remote images. NOTE: Some remote images may fail to load, so the list passed to callback may not be the same as remoteImages passed to this api.
Callback Parameters
- *List
1*
images`
Example Usage
DCEI.WildCastleDownloadRemoteImages(145, {"my_image_1", "another_image", "and_so_on"}, RemoteImagesDownloaded)
function RemoteImagesDownloaded(images)
for k, v in pairs(images) do
DCEI.LogMessage(v .. " Loaded")
end
end
string Actor(string actor)
string Actor(string actor)
Description
Parameters
- string
actor
the actor name to register.
Example Usage
--this creates an vfx model actor on your unit
on_hit = DCEI.Actor("COMBAT AreaAttack Impact FX")
Core.Unit.SendActorMessage(target_unit, "create", on_hit)
string Unit(string unit)
string Unit(string unit)
Description
Register a used unit. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
unit
the unit name to register.
Example Usage
local unit_type = DCEI.Unit("Goblin")
DCEI.CreateUnit(1, 1, unit_type, 0, 1)
string SimpleUnit(string unit)
string SimpleUnit(string unit)
Description
Parameters
- string
unit
the unit name to register.
Example Usage
local MissileData = {
list = {
-- ATTACK ITEMS
{
id = "attack_rock",
icon = DCEI.Texture("flat_icon_emoji_rock_1faa8_ipick"),
missile = DCEI.SimpleUnit("COMBAT Missile Rock"),
missile_type = MISSILE_TYPE.ATTACK,
impact = DCEI.SimpleUnit("COMBAT Unit Simple HitFx"),
spin_speed = -720,
},
{
id = "attack_brick",
icon = DCEI.Texture("flat_icon_emoji_brick_1f9f1_ipick"),
missile = DCEI.SimpleUnit("COMBAT Missile Brick"),
missile_type = MISSILE_TYPE.ATTACK,
},
{
id = "attack_soccer_ball",
icon = DCEI.Texture("flat_icon_emoji_soccer_ball_26bd_ipick"),
missile = DCEI.SimpleUnit("COMBAT Missile SoccerBall"),
missile_type = MISSILE_TYPE.ATTACK,
}
},
}
string Stats(string stats)
string Stats(string stats)
Description
DCEI.Stats(string stats_name)
, declare stats in lua scripts first, and then the stats_name can be used in SimpleDamageEffect.stats_name
or in DCEI.GetPlayerStats(int player_id, int stats_name
or in CollisionStatsApplierOptions.stats_name
Parameters
- string
stats
name of a stat.
Example Usage
This API is expirimental & in development.
No example usage yet.
string Effect(string effect)
string Effect(string effect)
Description
Register a used effect. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
effect
the effect name to register.
Example Usage
local effect = DCEI.Effect("EVENT Lightning Hook")
Core.Effect.Create(effect, pos.x, pos.y)
string Behavior(string behavior)
string Behavior(string behavior)
Description
Register a used behavior. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
behavior
the actor name to register.
Example Usage
local behavior = DCEI.Behavior("COMBAT Shield")
DCEI.ApplyBehaviorToSelf(target_unit, behavior, 1)
Related
string Sound(string sound)
string Sound(string sound)
Description
Register a used sound. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
sound
the sound name to register.
Example Usage
local sound = DCEI.Sound("dryad_bewitch_cast")
local volume = 2
DCEI.PlaySound(sound, volume)
string Tag(string tag)
string Tag(string tag)
Description
Register a used tag. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
tag
the tag name to register.
Example Usage
local tag = DCEI.Tag("human")
DCEI.ApplyTag(unit, tag, -1, 5)
string Upgrade(string upgrade)
string Upgrade(string upgrade)
Description
Register a used upgrade. This is mostly just used in Wild Sky. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
upgrade
the upgrade name to register.
Example Usage
local upgrade = DCEI.Upgrade("tech_tree_1")
DCEI.SetUpgradeLevelAsync(upgrade, 1)
string Font(string font)
string Font(string font)
Description
Register a used font. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
font
the font name to register.
Example Usage
-- As of editor 0.31 there isn't really a use case for this API, as no other APIs take a font
DCEI.Font("comic sans")
string Ability(string ability)
string Ability(string ability)
Description
Register a used ability. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
ability
the ability name to register.
Example Usage
local fireball_ability = DCEI.Ability("fireball")
DCEI.CastAbilityAtUnit(fireball_ability, caster_unit, target_unit, true)
string Weapon(string weapon)
string Weapon(string weapon)
Description
Register a used weapon. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
weapon
the weapon name to register.
Example Usage
local weapon = DCEI.Weapon("Standard MeleeUnit Weapon")
local unit_type = DCEI.Unit("Standard RangedUnit")
DCEI.AddUnitWeapon(unit_type, weapon)
string Particle(string particle)
string Particle(string particle)
Description
Register a used particle. Data used in Lua has to be registered in order for it to be loaded in-game.
Parameters
- string
particle
the particle name to register.
Example Usage
-- Placeholder example
local explosion_particle = DCEI.Particle("Explosion")
void SetScreenSleep(bool flag)
void SetScreenSleep(bool flag)
Description
If set to false, disable screen auto sleep; if set to true, use system screen sleep setting.
Parameters
- bool
flag
the screen sleep state to set.
Example Usage
-- Prevent the users phone screen from sleeping; useful for idle games
DCEI.SetScreenSleep(false)
float GetGameTime()
float GetGameTime()
Description
Returns the time passed since the game has started (in seconds).
Example Usage
local time = DCEI.GetGameTime()
DCEI.LogMessage(time)
void SetSimpleUnitMapBounds(SimpleUnitMapBoundOptions options)
void SetSimpleUnitMapBounds(SimpleUnitMapBoundOptions options)
Description
When simple units leave the map bounds, they are automatically removed. Includes a filter for player ID so that only units owned by a certain player will be removed.
Parameters
- SimpleUnitMapBoundOptions
options
options for setting simple unit map bounds.
Example Usage
local size = self:GetPlayableSize()
DCEI.SetSimpleUnitMapBounds({
center_x = 0,
center_y = 0,
width = 32,
height = 32,
player_id_remove_mask = -1,
})
object GetValueFromDataPath(String[] paths)
object GetValueFromDataPath(String[] paths)
Description
Returns a value from fields defined in the data editor, stored at the given data path. For example, if in the editor you’ve defined an Ability "Hero Marksman Ability"
with a base mana cost of 20, then in code you can read that base mana cost via DCEI.GetValueFromDataPath({ "abilities", "Hero Marksman Ability", "cost", "mana" })
See Notion guide on this feature.
This can only return either a string or integer. You can find a data object's json path names in the JSON view of Data Window and use them directly with the API. You can also right click any field in the editor and select "Copy Data Path" to copy the field's data path to the clipboard.
Parameters
- String[]
paths
the paths to retrieve values from. Accepts both lowerCamelCase and snake_case.
Example Usage
local data_path = {"units", "Standard MeleeUnit", "components", "unitStats", "radius"}
if DCEI.ValidateDataPath(data_path) then
local data_path_val = DCEI.GetValueFromDataPath(data_path)
DCEI.LogMessage(data_path_val)
end
bool ValidateDataPath(String[] paths)
bool ValidateDataPath(String[] paths)
Description
Returns true if value stored at the given data path is a string or integer. You can find a data object's json path names in the JSON view of Data Window and use them directly with the API. You can also right click any field in the editor and select "Copy Data Path" to copy the field's data path to the clipboard.
Parameters
- String[]
paths
the paths to validate. Accepts both lowerCamelCase and snake_case.
Example Usage
local data_path = {"units", "Standard MeleeUnit", "components", "unit_stats", "radius"}
if DCEI.ValidateDataPath(data_path) then
local data_path_val = DCEI.GetValueFromDataPath(data_path)
DCEI.LogMessage(data_path_val)
end
void TriggerAddSimulationCommandEvent(int player, TypedCallback<string, object> callback)
void TriggerAddSimulationCommandEvent(int player, TypedCallback<string, object> callback)
Description
Use in conjunction with DCEI.SendSimulationCommand
to allow Presentation.lua.txt script to run a function within the simulation layer by sending a payload that TriggerAddSimulationCommandEvent
can receive.
See SendPresentationCommand
& TriggerAddPresentationCommandEvent
to do the opposite (send an event from simulation script to presentation script)
See Presentation vs Simulation scripts.
Parameters
- int
player
player id of the triggering player - TypedCallback<string, object>
callback
the callback function that is run when the event is triggered. The string parameter is the command sent from presentation script, usually json encoded for more info.
Callback Parameters
- String
command
- Object
context
Example Usage
--this runs in simulation script, receiving command from presentation script
DCEI.TriggerAddSimulationCommandEvent(
1,
function(payload)
local command = json.decode(payload)
if command.type == "set_speed" then
speed = command.speed
DCEI.LogMessage("Speed change to: " .. speed)
elseif command.type == "pause_unpause" then
pause = not pause
end
end
)
-- Put this in presentation script, when the button is clicked, send command to simulation script
DCEI.SetOnClickCallback(
window,
function()
DCEI.SendSimulationCommand(
json.encode(
{
type = "pause_unpause"
}
)
)
end
)
void SendSimulationCommand(string command, object context)
void SendSimulationCommand(string command, object context)
Description
Use in conjunction with DCEI.TriggerAddSimulationCommandEvent
to allow Presentation.lua.txt script to run a function within the simulation layer by sending a payload that TriggerAddSimulationCommandEvent
can receive.
See SendPresentationCommand
& TriggerAddPresentationCommandEvent
to do the opposite (send an event from simulation script to presentation script)
See Presentation vs Simulation scripts.
Parameters
- string
command
the command sent to simulation script, usually json encoded to contain more information - object
context
a Lua table (or function). Use this to keep track of the context info for a sequence of actions spreading across simulation and presentation.
Example Usage
--this runs in simulation script, receiving command from presentation script
DCEI.TriggerAddSimulationCommandEvent(
1,
function(payload)
local command = json.decode(payload)
if command.type == "set_speed" then
speed = command.speed
DCEI.LogMessage("Speed change to: " .. speed)
elseif command.type == "pause_unpause" then
pause = not pause
end
end
)
-- Put this in presentation script, when the button is clicked, send command to simulation script
DCEI.SetOnClickCallback(
window,
function()
DCEI.SendSimulationCommand(
json.encode(
{
type = "pause_unpause"
}
)
)
end
)
void TriggerAddPresentationCommandEvent(TypedCallback<string, object> callback)
void TriggerAddPresentationCommandEvent(TypedCallback<string, object> callback)
Description
This establishes a function to run within Presentation.lua.txt
script when receiving an event from simulation Trigger.lua.txt
sent with the DCEI.SendPresentationCommand
API.
See SendSimulationCommand
& TriggerAddSimulationCommandEvent
to do the opposite (send an event from presentation script to simulation script)
See Presentation vs Simulation scripts for more information about the two scripting layers.
Parameters
- TypedCallback<string, object>
callback
the callback function that is run when the event is triggered. the string parameter is the command sent to presentation scrip, usually json encoded for more info.
Callback Parameters
- String
command
- Object
context
Example Usage
--this runs in presentation script, receiving command from simulation script
DCEI.TriggerAddPresentationCommandEvent(function(payload)
local command = json.decode(payload)
if command.type == "pause_unpause" then
pause = not pause
end
end)
-- Put this in simulation script, when the button is clicked, send command to presentation script
DCEI.SetOnClickCallback(
window,
function()
DCEI.SendPresentationCommand(
1,
json.encode(
{
type = "pause_unpause"
}
)
)
end
)
void SendPresentationCommand(int player, string command, object simulationContext)
void SendPresentationCommand(int player, string command, object simulationContext)
Description
Send a payload of information in the simulation Trigger.lua.txt
that will be received in Presentation.lua.txt
script by the TriggerAddPresentationCommandEvent
API.
See SendSimulationCommand
& TriggerAddSimulationCommandEvent
to do the opposite (send an event from presentation script to simulation script)
See Presentation vs Simulation scripts for more information about the two scripting layers.
Parameters
- int
player
player id of the triggering player - string
command
the command sent to simulation script, usually json encoded to contain more information - object
simulationContext
a Lua table (or function). Use this to keep track of the context info for a sequence of actions spreading across simulation and presentation.
Example Usage
--this runs in presentation script, receiving command from simulation script
DCEI.TriggerAddPresentationCommandEvent(function(payload)
local command = json.decode(payload)
if command.type == "pause_unpause" then
pause = not pause
end
end)
-- Put this in simulation script, when the button is clicked, send command to presentation script
DCEI.SetOnClickCallback(
window,
function()
DCEI.SendPresentationCommand(
1,
json.encode(
{
type = "pause_unpause"
}
)
)
end
)
void ShareDataWithPresentation(string key, object data)
void ShareDataWithPresentation(string key, object data)
Description
The data argument is a Lua table that needs to be accessed from presentation layer, and key is a string identifier.
See Presentation vs Simulation scripts.
Parameters
- string
key
string identifier. Use with GetSharedDataFromSimulation to retrieve data in presentation script. - object
data
a Lua table to share with presentation layer with DCEI.GetSharedDataFromSimulation
Example Usage
-- TRIGGERS
local function OnGoldDummySpawn()
local u = DCEI.TriggeringUnit
local key = "my_unit_key"
DCEI.ShareDataWithPresentation(key, { unit = u })
GMUI.RunPresentationFunction("AttachUiToGoldDummyUnit", key)
end
Presentation.lua.txt (Presentation)
-- FUNCTIONS
function AttachUiToGoldDummyUnit(key)
local data = DCEI.GetSharedDataFromSimulation(key)
local unit = data.unit
-- create and attach coin to dummy unit
local layout = GMUI.Layout.New({
name = "Game/Coin",
})
local options = {}
DCEI.AttachFrameToUnit(layout.Frame, unit, options, USE_CURRENT_UI_ROOT)
end
object GetSharedDataFromSimulation(string key)
object GetSharedDataFromSimulation(string key)
Description
If a Lua table data is shared from simulation with the given key, this API returns a read-only view of that data, accessed like a regular Lua table. When the original Lua table is updated in simulation, the view will reflect the updated values as well.
See Presentation vs Simulation scripts.
Parameters
- string
key
key used to retrieve value shared byDCEI.ShareDataWithPresentation
Example Usage
-- TRIGGERS
local function OnGoldDummySpawn()
local u = DCEI.TriggeringUnit
local key = "my_unit_key"
DCEI.ShareDataWithPresentation(key, { unit = u })
GMUI.RunPresentationFunction("AttachUiToGoldDummyUnit", key)
end
Presentation.lua.txt (Presentation)
-- FUNCTIONS
function AttachUiToGoldDummyUnit(key)
local data = DCEI.GetSharedDataFromSimulation(key)
local unit = data.unit
-- create and attach coin to dummy unit
local layout = GMUI.Layout.New({
name = "Game/Coin",
})
local options = {}
DCEI.AttachFrameToUnit(layout.Frame, unit, options, USE_CURRENT_UI_ROOT)
end
void TriggerAddUpdateEvent(TypedCallback<float> callback)
void TriggerAddUpdateEvent(TypedCallback<float> callback)
Description
Run the callback function every presentation frame, which is way higher than simulation frame (16 fps fixed for now). This can be used to create smooth UI animations.
Parameters
- TypedCallback<float>
callback
the callback function that is run every presentation frame.
Callback Parameters
- Single
delta_time
Example Usage
local rotation = 0
DCEI.TriggerAddUpdateEvent(
function(delta_time)
if not pause then
rotation = rotation + speed * 90 * delta_time
DCEI.SetFrameRotation(window, rotation)
end
end
)
object CreateCustomIapProductData()
object CreateCustomIapProductData()
Description
Returns a table for custom in-app product data. Most games should use the Shop Mod to handle IAP.
Example Usage
local product_list = DCEI.CreateCustomIapProductData()
-- construct product list from IAP data
for index, iap in ipairs(iap_data.product_list) do
local product_id = iap.product_id
if product_id then
-- use product_id as IAP reference name
IAP[product_id] = iap
-- convert price and item product data into protected values
ProtectItemData(product_id)
-- store USD price for analytics revenue logging
local usd_price = mod.GetProductPriceUSD(product_id)
-- add items with usd price to product list
if usd_price then
local custom_product = DCEI.CreateCustomIapProduct(product_id, usd_price)
DCEI.AddCustomIapProduct(product_list, custom_product)
-- DCEI.LogMessage("> Initialized IAP [" .. product_id .. "][usd_price " .. usd_price .. "]")
end
else
-- error handling
DCEI.LogError("> IAP [" .. index .. "] has invalid product_id")
return
end
end
end
object CreateCustomIapProduct(string productId, float price)
object CreateCustomIapProduct(string productId, float price)
Description
Returns a custom in-app product with the values given. Most games should use the Shop Mod to handle IAP.
Parameters
- string
productId
the product ID. - float
price
the price for the product.
Example Usage
local product_list = DCEI.CreateCustomIapProductData()
-- construct product list from IAP data
for index, iap in ipairs(iap_data.product_list) do
local product_id = iap.product_id
if product_id then
-- use product_id as IAP reference name
IAP[product_id] = iap
-- convert price and item product data into protected values
ProtectItemData(product_id)
-- store USD price for analytics revenue logging
local usd_price = mod.GetProductPriceUSD(product_id)
-- add items with usd price to product list
if usd_price then
local custom_product = DCEI.CreateCustomIapProduct(product_id, usd_price)
DCEI.AddCustomIapProduct(product_list, custom_product)
-- DCEI.LogMessage("> Initialized IAP [" .. product_id .. "][usd_price " .. usd_price .. "]")
end
else
-- error handling
DCEI.LogError("> IAP [" .. index .. "] has invalid product_id")
return
end
end
end
object AddCustomIapProduct(CustomIapProductData data, CustomIapProduct product)
object AddCustomIapProduct(CustomIapProductData data, CustomIapProduct product)
Description
Combines the custom in app product data and product returned from the above functions and returns a whole product. Most games should use the Shop Mod to handle IAP.
Parameters
- CustomIapProductData
data
data structure created from CreateCustomIapProductData(), - CustomIapProduct
product
product structure created from CreateCustomIapProduct().
Example Usage
local product_list = DCEI.CreateCustomIapProductData()
local iap_item = DCEI.CreateCustomIapProduct("product_1", 1)
DCEI.AddCustomIapProduct(product_list, iap_item)
float GetProtectedValue(string key)
float GetProtectedValue(string key)
Description
Returns a protected value from its key.
Protected values are encoded to make it harder for cheaters using a simple memory reader to find and modify the value. Be sure not to store the value ever in a Lua variable. This would defeat the purpose, by still allowing cheaters to easy read and modify the value before/after using Get/SetProtected value.
When you no longer need a protected value, it's good practice to call ClearProtectedValue.
Parameters
- string
key
key associated with the value.
Example Usage
function GetPlayerWinterCoin()
return math.floor(DCEI.GetProtectedValue(data.safe.winter_coin))
end
function AddPlayerWinterCoin(value, skip_commit)
SetPlayerWinterCoin(value + GetPlayerWinterCoin(), skip_commit)
end
function SetPlayerWinterCoin(value, skip_commit)
DCEI.SetProtectedValue(data.safe.winter_coin, value)
if not skip_commit then
Bank:CommitWinterCoin()
end
end
function GetPlayerSpringCoin()
return math.floor(DCEI.GetProtectedValue(data.safe.spring_coin))
end
function AddPlayerSpringCoin(value, skip_commit)
SetPlayerSpringCoin(value + GetPlayerSpringCoin(), skip_commit)
end
function SetPlayerSpringCoin(value, skip_commit)
DCEI.SetProtectedValue(data.safe.spring_coin, value)
if not skip_commit then
Bank:CommitSpringCoin()
end
end
void ClearProtectedValue(string key)
void ClearProtectedValue(string key)
Description
Clears the protected value pair of a given key.
Protected values are encoded to make it harder for cheaters using a simple memory reader to find and modify the value. Be sure not to store the value ever in a Lua variable. This would defeat the purpose, by still allowing cheaters to easy read and modify the value before/after using Get/SetProtected value.
When you no longer need a protected value, it's good practice to call ClearProtectedValue.
Parameters
- string
key
the key to clear.
Example Usage
-- Setting value
DCEI.SetProtectedValue("path_key_string", 23)
DCEI.Wait(5)
DCEI.ClearProtectedValue("path_key_string")
void SetProtectedValue(string key, float value)
void SetProtectedValue(string key, float value)
Description
Protected values are encoded to make it harder for cheaters using a simple memory reader to find and modify the value. Be sure not to store the value ever in a Lua variable. This would defeat the purpose, by still allowing cheaters to easy read and modify the value before/after using Get/SetProtected value.
When you no longer need a protected value, it's good practice to call ClearProtectedValue.
Parameters
- string
key
the key of the pair. - float
value
the value of the pair.
Example Usage
function GetPlayerWinterCoin()
return math.floor(DCEI.GetProtectedValue(data.safe.winter_coin))
end
function AddPlayerWinterCoin(value, skip_commit)
SetPlayerWinterCoin(value + GetPlayerWinterCoin(), skip_commit)
end
function SetPlayerWinterCoin(value, skip_commit)
DCEI.SetProtectedValue(data.safe.winter_coin, value)
if not skip_commit then
Bank:CommitWinterCoin()
end
end
function GetPlayerSpringCoin()
return math.floor(DCEI.GetProtectedValue(data.safe.spring_coin))
end
function AddPlayerSpringCoin(value, skip_commit)
SetPlayerSpringCoin(value + GetPlayerSpringCoin(), skip_commit)
end
function SetPlayerSpringCoin(value, skip_commit)
DCEI.SetProtectedValue(data.safe.spring_coin, value)
if not skip_commit then
Bank:CommitSpringCoin()
end
end
void SetEffectFieldValueForPlayer(int playerId, string effectName, String[] path, object value)
void SetEffectFieldValueForPlayer(int playerId, string effectName, String[] path, object value)
Description
Set effect field value for player with playerId. This is similar to effect hooks but faster because it doesn't need to run lua every time the effect runs, and result can be cached.
Parameters
- int
playerId
player id - string
effectName
name of the effect to modify - String[]
path
field path to modify. You can right-click on a field in the data editor and select "copy data path" to find the correct path to input. - object
value
the value to set the effect field to for this player.
Example Usage
local player_id = 1
local effect = DCEI.Effect("Standard Damage")
local effect_path = {"effects", "Standard Damage", "damage", "damageAmount"}
local value = 15
DCEI.SetEffectFieldValueForPlayer(player_id, effect, effect_path, value)
float ApplyModifier(BehaviorModifier modifier, float value)
float ApplyModifier(BehaviorModifier modifier, float value)
Description
Applies a behavior modifier to a value, returning the scaled/modified value. This makes it easier to mimic value scaling in Lua the same way these values would be scaled via data.
Parameters
- BehaviorModifier
modifier
behavior modifier to apply. - float
value
base value to scale by the BehaviorModifier.
Example Usage
local example_value = DCEI.ApplyModifier(
{
scaled = 5,
unscaled = 0,
additive_factor = 1,
positive_unified_factor = 1,
negative_unified_factor = 0,
multiplier_factor = 1,
},
5
)
DCEI.LogMessage(example_value)
bool IsPointOnNavMesh(float x, float z)
bool IsPointOnNavMesh(float x, float z)
Description
Returns true if the given coordinates are on the nav mesh.
Parameters
- float
x
the x coordinate. - float
z
the z coordinate.
Example Usage
local x = 16
local y = 16
local check_point = DCEI.IsPointOnNavMesh(x, y)
DCEI.LogMessage(tostring(check_point))
Float2 GetClosestPointOnNavMesh(float x, float z)
Float2 GetClosestPointOnNavMesh(float x, float z)
Description
Returns the closest coordinates on the nav mesh to the given coordinates.
Parameters
- float
x
the x coordinate. - float
z
the z coordinate.
Example Usage
local point = DCEI.GetClosestPointOnNavMesh(15, 15)
DCEI.LogMessage("x: " .. point.x .. " y: " .. point.y)
void AddNavmeshCut(string prop_tag)
void AddNavmeshCut(string prop_tag)
Description
Add a navmesh cut according to prop's tag, the navmesh cut will share the same position, rotation and shape of this prop.
Parameters
- string
prop_tag
the prop's tag.
Example Usage
-- Prop tags can be definined in the terrain editor by selecting a prop and changing the "Prop Tag" field.
DCEI.AddNavmeshCut("prop_test")
void SetPropVisibility(string prop_tag, bool visibility)
void SetPropVisibility(string prop_tag, bool visibility)
Description
Set the visibility of prop according to prop tag.
Parameters
- string
prop_tag
the prop's tag. - bool
visibility
if true, make the prop visible.
Example Usage
-- Prop tags can be definined in the terrain editor by selecting a prop and changing the "Prop Tag" field.
DCEI.SetPropVisibility("prop_test", false)
void EnableNavmeshCut(string prop_tag, bool enable = True)
void EnableNavmeshCut(string prop_tag, bool enable = True)
Description
Enable/disable a navmesh cut according to prop tag.
Parameters
- string
prop_tag
the prop's tag. - bool
enable
if true, enable the navmesh cut.
Example Usage
-- Prop tags can be definined in the terrain editor by selecting a prop and changing the "Prop Tag" field.
DCEI.AddNavmeshCut("prop_test")
DCEI.EnableNavmeshCut("prop_test", true)
DCEI.Wait(5)
DCEI.EnableNavmeshCut("prop_test", false)
void SetSpeedTurbo(bool turbo)
void SetSpeedTurbo(bool turbo)
Description
Toggles the built-in 2x speed button. Commonly used to disable the 2x speed during a tutorial and cinematic and/or resume it again after the tutorial/cinematic ends.
Parameters
- bool
turbo
if true, enable turbo (2x) speed.
Example Usage
function game.SetSpeedFactor(factor)
DCEI.SetSpeedTurbo(false)
DCEI.SetSpeedFactor(factor)
end
object GetDataContextValue(string key)
object GetDataContextValue(string key)
Description
Used by Wild Sky to get some level data context, such as difficulty or if the level has already been completed by players or not.
Parameters
- string
key
the key for the data index to retrieve.
Example Usage
local completed = DCEI.GetDataContextValue("Completed") --This value returns "true" if players have already COMPLETED the level
if not completed then -- Only play Dialogue if players have not already completed the level
gameStartBighead()
end
object GetCardDamageStats()
object GetCardDamageStats()
Description
Returns a table containing the card damage stats. Damage effects in the data editor need a "card" field for this damage stacking to be properly counted. When counted, the in-game dev menu can be set to display these damage counts.
Example Usage
function ProcessBattleData()
local stats = DCEI.GetCardDamageStats()
local damage_total = 0
local battle_data = {}
for unit_name, damage_value in pairs(stats) do
damage_total = damage_total + damage_value
table.insert(battle_data, { name = unit_name, damage = damage_value })
end
DCEI.ResetCardDamageStats()
return battle_data
end
void ResetCardDamageStats()
void ResetCardDamageStats()
Description
Example Usage
function ProcessBattleData()
local stats = DCEI.GetCardDamageStats()
local damage_total = 0
local battle_data = {}
for unit_name, damage_value in pairs(stats) do
damage_total = damage_total + damage_value
table.insert(battle_data, { name = unit_name, damage = damage_value })
end
DCEI.ResetCardDamageStats()
return battle_data
end
void TriggerOnFocusChange(TypedCallback<bool> callback)
void TriggerOnFocusChange(TypedCallback<bool> callback)
Description
This triggers the callback function on focus change (for the game window).
Parameters
- TypedCallback<bool>
callback
the callback function that is run.
Callback Parameters
- Boolean
has_focus
Example Usage
function OnFocusChange()
DCEI.LogMessage("Focus changed.")
end
DCEI.TriggerOnFocusChange(OnFocusChange)
void GarbageCollect()
void GarbageCollect()
Description
Example Usage
function GarbageCollect()
DCEI.LogMessage("GC before: " .. collectgarbage("count"))
DCEI.GarbageCollect()
DCEI.LogMessage("GC after: " .. collectgarbage("count"))
end
int GetLuaMemorySize()
int GetLuaMemorySize()
Description
Example Usage
local size = DCEI.GetLuaMemorySize()
DCEI.LogMessage(size)
double GetLevelDataLoadingTime()
double GetLevelDataLoadingTime()
Description
Returns the level data loading time.
Example Usage
local loading_time = DCEI.GetLevelDataLoadingTime()
DCEI.LogMessage(loading_time)
void Wait(float time, bool useRealTime)
void Wait(float time, bool useRealTime)
Description
Waits for the given amount of time. Note that Wait cannot be used inside TriggerAddUnitSpawnEvent callback functions or main body.
This type of Wait will hold up all following code in the thread, even code in another function. Sometimes this behavior is necessary. However, when it is not, such behavior can make your code more difficult to troubleshoot and more prone to unexpected behavior, so other types of timers like Core timers should be used.
For more examples of when different times of waits or timers should be used, see this notion guide.
Parameters
- float
time
the amount of time to wait. - bool
useRealTime
if true, uses real time.
Example Usage
function OnFocusChange()
DCEI.LogMessage("Focus changed.")
DCEI.Wait(5, false)
DCEI.LogMessage("It has been 5 seconds since the focus changed.")
end
DCEI.TriggerOnFocusChange(OnFocusChange)