FOnline Engine
Current master GitHub
Documentation Docs/en/reference/effect-format/runtime.md

Effect Runtime And Script API

Generated reference. Do not edit directly. Update BuildTools/EffectFormatInterface.json, then run python BuildTools/docs_effect_format.py --write.

Index Syntax Render state Resources Baking Runtime Validation Canonical JSON Guide
Stable ID Rule Requirement Why Source
effect-format.runtime.state-and-metadata Runtime artifact pair RenderEffect loads the baked .fofx source for pass/render state and one .fofx-N-info artifact per pass for reflected resource positions. Changing only a shader binary cannot change pass count or blend/depth state. Source/Frontend/Rendering.cpp
effect-format.runtime.cache-key Path-only effect cache EffectManager caches one mutable RenderEffect object per resource path. Re-loading the same path returns the existing object. ScriptValueBuf and per-frame optional buffers belong to the cached object, not to an effect slot. Source/Client/EffectManager.cpp
effect-format.runtime.first-usage First-load EffectUsage The first load of a path fixes that RenderEffect object’s EffectUsage. Do not reuse one path across incompatible ImGui, QuadSprite, Primitive, or Model usage categories. The cache key omits EffectUsage and later loads return the first object without rebuilding its vertex layout or pipeline assumptions. Source/Client/EffectManager.cpp, Source/Frontend/Rendering.h
effect-format.runtime.script-value-lifetime ScriptValue persistence An effect declaring ScriptValueBuf receives a zeroed buffer on first load. Values persist on the cached path until overwritten or explicitly cleared; SetEffect does not clear them. Switching to another path selects another object’s buffer, while switching back to a previously loaded path restores that object’s prior values. Source/Client/EffectManager.cpp, Source/Client/Client.cpp
effect-format.runtime.script-value-target Script-value target resolution Script writes resolve the currently selected effect for one EffectType/subtype, require it to be loaded, and require that it declares ScriptValueBuf. Writing a slot on a passthrough/default effect without ScriptValueBuf is a script error. Source/Client/Client.cpp
effect-format.runtime.per-frame-update Per-frame buffer updates Every loaded effect is visited each frame; TimeBuf and RandomValueBuf are allocated/refreshed only when reflection marks them as needed. Declaring a built-in buffer opts the effect into its Engine producer. Source/Client/EffectManager.cpp
effect-format.runtime.default-selection Default effect resolution An empty SetEffect path resolves back to the slot’s default effect; a non-empty path loads it using the default effect’s EffectUsage. Projects can temporarily override a slot and restore the Engine/project default without naming its path. Source/Client/EffectManager.cpp

Script methods

Stable ID Signature Sides Behavior Errors Source
effect-format.script.set-effect void Game.SetEffect(EffectType effectType, int64 effectSubtype, string effectPath) client, mapper Selects a path for the requested effect slot or restores the default when effectPath is empty. Invalid subtypes and missing/broken effects throw. The selected path must be compatible with the slot’s EffectUsage. Source/Scripting/ClientGlobalScriptMethods.cpp
effect-format.script.set-value void Game.SetEffectScriptValue(EffectType effectType, int64 effectSubtype, int valueIndex, float value) client, mapper Writes one float into the selected cached effect object’s ScriptValueBuf. The index must be in range and the selected effect must be loaded and declare ScriptValueBuf. Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/EffectManager.cpp
effect-format.script.set-values void Game.SetEffectScriptValues(EffectType effectType, int64 effectSubtype, int valueStartIndex, float[] values, int valuesOffset = 0, int valuesCount = -1) client, mapper Writes a contiguous slice of values in one native call; valuesCount -1 selects the remaining input range. Input offset/count and destination range are validated before resolving and writing the effect. Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/Client.cpp
effect-format.script.clear-values void Game.ClearEffectScriptValues(EffectType effectType, int64 effectSubtype) client, mapper Zeroes the entire ScriptValueBuf of the selected cached effect object. The selected effect must be loaded and declare ScriptValueBuf. Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Client/EffectManager.cpp
Start typing to search.