Module twdll.tweakers

Engine tweakers and campaign variables runtime access.

Provides unified read/write access to all 3,731 internal engine variables:

  • Direct Tweakers (~2,341): Shaders, battle physics, camera, terrain and UI — updated in-place in engine memory.
  • KV Tweakers (518): Live database row cells in RAM (TWEAKABLE_KV_ITEM).
  • Campaign Variables (714): Routed directly to the active CAMPAIGN_MODEL (+0x1100) and EMPIRE_DATABASES (+0x0000).
  • Campaign AI Variables (158): CAI evaluator weights and priority thresholds.

All modified values automatically snapshot their original vanilla state and are cleanly restored on Lua teardown / game reload.

Engine Evaluation Timing & Subsystem Mechanics

Engine tweakers are read and evaluated by different engine subsystems at different times:

  1. Per-frame / Runtime Dynamic: Visuals, terrain seasons, camera constraints, shader toggles, and general action points. Changes take effect immediately.
  2. Subsystem / Event-driven: CAI strategic goals, autoresolver modifiers, marriage odds, looting income formulas, and cultural conversion. Changes take effect whenever that specific calculation is executed by the engine.
  3. Initialization-time / Cache-only: World generation parameters and static baseline tables. These should be modified as early as possible at top level in the campaign's scripting.lua starting script (before world initialization events fire).

For the complete catalog of all 3,731 variables, categories, and descriptions, see Complete Engine Tweakers Inventory.

Usage:

-- 1. Direct property access:
twdll.tweakers.general_admiral_action_point_bonus.value = 500
twdll.tweakers.terrain_override_season.value = 3  -- 0=Spring, 1=Summer, 2=Autumn, 3=Winter
twdll.tweakers.AI_FORCE_ATTACK_PLAN.value = true

-- 2. Find and inspect a tweaker:
local t = twdll.tweakers.Find("max_traits")
if t then
    print(t.name)         --> "max_traits"
    print(t.category)     --> "all"
    print(t.description)  --> description string
    print(t.value)        --> 15
    t.value = 30          -- update value
    t:SetInt(30)          -- or via method
end

-- 3. Iterate all available tweakers:
for _, tw in ipairs(twdll.tweakers.GetList()) do
    if tw.category == "Campaign Variable Tweakers" then
        print(tw.name, tw.value)
    end
end

Functions

Dump () Dumps all registered engine tweakers from the global registry to twdll.log.
Find (name) Finds an engine tweaker object by name.
GetBool (name) Gets the boolean value of an engine tweaker by name.
GetBool () Gets the current boolean flag value of the tweaker.
GetCategory () Category of the tweaker (e.g.
GetDescription () Detailed description / documentation tooltip from the engine developers.
GetFile () Source code filename in the CA repository where this tweaker was defined.
GetFloat (name) Gets the float value of an engine tweaker by name.
GetFloat () Gets the current float value of the tweaker.
GetInt () Gets the current integer value of the tweaker.
GetInt (name) Gets the integer value of an engine tweaker by name.
GetLine () Source code line number where this tweaker was defined.
GetList () Returns a list of all registered engine tweakers.
GetName () Name of the tweaker (e.g.
GetRawValue () Gets the raw 32-bit integer representation of the tweaker's memory value.
GetTitle () Tooltip title of the tweaker.
GetValue () Gets the polymorphic value of the tweaker (auto-detected integer/float/bool).
SetBool (value) Sets the boolean flag value of the tweaker with state rollback on teardown.
SetBool (name, value) Sets the boolean value of an engine tweaker with state rollback on teardown.
SetFloat (name, value) Sets the float value of an engine tweaker with state rollback on teardown.
SetFloat (value) Sets the float value of the tweaker with state rollback on teardown.
SetInt (value) Sets the integer value of the tweaker with state rollback on teardown.
SetInt (name, value) Sets the integer value of an engine tweaker with state rollback on teardown.
SetRawValue (value) Sets the raw 32-bit integer representation of the tweaker's memory value.
SetValue (value) Sets the polymorphic value of the tweaker with auto-detected type.


Functions

Dump ()
Dumps all registered engine tweakers from the global registry to twdll.log.

Returns:

    integer total count of registered engine tweakers discovered

Usage:

    twdll.tweakers.Dump()
Find (name)
Finds an engine tweaker object by name.

Parameters:

  • name string tweaker name (e.g. "maxtraits", "AIFORCEATTACKPLAN")

Returns:

    TWEAKER_SCRIPT_INTERFACE or nil tweaker object, or nil if not found

Usage:

    local t = twdll.tweakers.Find("max_traits")
t.value = 30
GetBool (name)
Gets the boolean value of an engine tweaker by name.

Parameters:

Returns:

    boolean or nil current boolean value, or nil if not found
GetBool ()
Gets the current boolean flag value of the tweaker.

Returns:

    boolean current boolean flag
GetCategory ()
Category of the tweaker (e.g. "Campaign Variable Tweakers", "KV Tweakers").

Returns:

    string tweaker category
GetDescription ()
Detailed description / documentation tooltip from the engine developers.

Returns:

    string tweaker description
GetFile ()
Source code filename in the CA repository where this tweaker was defined.

Returns:

    string source code file path
GetFloat (name)
Gets the float value of an engine tweaker by name.

Parameters:

Returns:

    number or nil current float value, or nil if not found
GetFloat ()
Gets the current float value of the tweaker.

Returns:

    number current float value
GetInt ()
Gets the current integer value of the tweaker.

Returns:

    integer current integer value
GetInt (name)
Gets the integer value of an engine tweaker by name.

Parameters:

Returns:

    integer or nil current value, or nil if not found
GetLine ()
Source code line number where this tweaker was defined.

Returns:

    integer source line number
GetList ()
Returns a list of all registered engine tweakers.

Returns:

    table array of TWEAKERSCRIPTINTERFACE objects

Usage:

     local list = twdll.tweakers.GetList()
for i, t in ipairs(list) do
    print(t.name, t.category, t.value)
end
GetName ()
Name of the tweaker (e.g. "max_traits").

Returns:

    string tweaker name
GetRawValue ()
Gets the raw 32-bit integer representation of the tweaker's memory value.

Returns:

    integer raw 32-bit integer value
GetTitle ()
Tooltip title of the tweaker.

Returns:

    string tweaker title
GetValue ()
Gets the polymorphic value of the tweaker (auto-detected integer/float/bool).

Returns:

    any current value
SetBool (value)
Sets the boolean flag value of the tweaker with state rollback on teardown.

Parameters:

  • value boolean new boolean flag

Returns:

    boolean true on success
SetBool (name, value)
Sets the boolean value of an engine tweaker with state rollback on teardown.

Parameters:

  • name string tweaker name
  • value boolean new boolean flag

Returns:

    boolean true on success
SetFloat (name, value)
Sets the float value of an engine tweaker with state rollback on teardown.

Parameters:

  • name string tweaker name
  • value number new float value

Returns:

    boolean true on success
SetFloat (value)
Sets the float value of the tweaker with state rollback on teardown.

Parameters:

  • value number new float value

Returns:

    boolean true on success
SetInt (value)
Sets the integer value of the tweaker with state rollback on teardown.

Parameters:

  • value integer new integer value

Returns:

    boolean true on success
SetInt (name, value)
Sets the integer value of an engine tweaker with state rollback on teardown.

Parameters:

  • name string tweaker name
  • value integer new integer value

Returns:

    boolean true on success
SetRawValue (value)
Sets the raw 32-bit integer representation of the tweaker's memory value.

Parameters:

  • value integer raw 32-bit integer value

Returns:

    boolean true on success
SetValue (value)
Sets the polymorphic value of the tweaker with auto-detected type.

Parameters:

  • value any new value

Returns:

    boolean true on success
generated by LDoc 1.5.0