Difference between revisions of "Quick Stat Tweaks"

From Zero-K
Jump to navigation Jump to search
(Added closing bracket to the encoded string.)
 
(28 intermediate revisions by 5 users not shown)
Line 1: Line 1:
The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] to get started on full modding.
+
The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.
  
[[File:Tweakunitswindow.jpg]]
+
[[File:Tweakunitsdefs.png]]
 +
 
 +
Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].
  
 
== Workflow ==
 
== Workflow ==
The Tweak Units modoption overwrites unit paramers (called unitDefs) as they are loaded. The modoption requires a base64 encoded lua array of differences. Here is how to use it.
+
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.
* Make a lua table in an empty file.
+
* Make a Lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the internal name of the unit to your table.
+
* For each unit you wish to modify, add an empty table indexed by the [[Internal unit names|internal name]] of the unit to your table.
 
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
 
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
 
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
 
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org/ Base 64 encode] your table.
+
* [https://www.base64encode.org Base64 encode] your table.
 
* Put the base 64 encoding of your table into the Tweak Units modoption.
 
* Put the base 64 encoding of your table into the Tweak Units modoption.
 
* Start the game.
 
* Start the game.
 
* Check infolog.txt in your install directory and fix your syntax errors.
 
* Check infolog.txt in your install directory and fix your syntax errors.
  
Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters.
+
Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.
 +
 
 +
== Limitations ==
 +
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.
 +
 
 +
== Simple Example ==
 +
In this example we make Glaive faster and cheaper.
 +
 
 +
Start with an empty Lua table.
 +
<syntaxhighlight lang="lua">{
 +
}</syntaxhighlight>
 +
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
 +
<syntaxhighlight lang="lua">{
 +
    cloakraid = {},
 +
}</syntaxhighlight>
 +
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's cost is 'metalCost' and its speed is just 'speed'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
 +
<syntaxhighlight lang="lua">{
 +
    cloakraid = {
 +
        metalCost = 50,
 +
        speed = 240,
 +
    },
 +
}</syntaxhighlight>
 +
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
 +
<code style="display:block;overflow:auto">ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1ldGFsQ29zdCA9IDUwLAogICAgICAgIHNwZWVkID0gMjQwLAogICAgfSwKfQ==</code>
 +
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
 +
<samp><pre>[f=-000001] Loading UnitDefs_posts
 +
[f=-000001] Loading tweakunits modoption        <------
 +
[f=-000001] Loading tweakunits for cloakraid    <------
 +
[f=-000001] Loading FeatureDefs_posts
 +
[f=-000001] Loading WeaponDefs_posts
 +
[f=-000001] Loading ArmorDefs_posts</pre></samp>
 +
 
 +
== Advanced Example ==
 +
In this example we will change Bandit's damage and range, and add it to the Glaive changes.
 +
 
 +
As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.
 +
<syntaxhighlight lang="lua">{
 +
    cloakraid = {
 +
        metalCost = 50,
 +
        speed = 240,
 +
    },
 +
    shieldraid = {},
 +
}</syntaxhighlight>
 +
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
 +
<syntaxhighlight lang="lua">{
 +
    cloakraid = {
 +
        metalCost = 50,
 +
        speed = 240,
 +
    },
 +
    shieldraid = {
 +
        weaponDefs = {
 +
            LASER = {
 +
                range = 600,
 +
                damage = {
 +
                    default = 50,
 +
                },
 +
            },
 +
        },
 +
    },
 +
}</syntaxhighlight>
 +
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
 +
<code style="display:block;overflow:auto">e2Nsb2FrcmFpZD17bWV0YWxDb3N0PTUwLHNwZWVkPTI0MCx9LHNoaWVsZHJhaWQ9e3dlYXBvbkRlZnM9e0xBU0VSPXtyYW5nZT02MDAsZGFtYWdlPXtkZWZhdWx0PTUwLH0sfSx9LH0sfQ==</code>
 +
 
 +
== Mass post-processing ==
 +
 
 +
The above examples deal with specific values for a single unit (e.g. "make Glaive have 240 speed").
 +
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.
 +
 
 +
Here's an example:
 +
<syntaxhighlight lang="lua">for name, ud in pairs(UnitDefs) do
 +
if ud.speed then
 +
ud.speed = ud.speed*10
 +
else
 +
ud.health = ud.health*5
 +
end
 +
 
 +
if ud.metalcost then
 +
ud.metalcost = ud.metalcost*2
 +
end
 +
end</syntaxhighlight>
 +
 
 +
<var>UnitDefs</var> is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE (notice how it's <var>metalcost</var> and not <var>metalCost</var>!). This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics, and makes all units twice as expensive. Some fields may be <code>nil</code> (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.
 +
 
 +
Happy hacking!
 +
 
 +
[[File:Zk_1_7_11_0_cover.jpg|frame|center]]
  
== Example ==
+
[[Category:Development]]{{Navbox manual}}

Latest revision as of 12:54, 22 December 2023

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see Mod Creation and How To Play Mods to get started on full modding.

Tweakunitsdefs.png

Stat tweaks can be saved and shared as a Custom Mode.

Workflow[edit]

The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.

  • Make a Lua table in an empty file.
  • For each unit you wish to modify, add an empty table indexed by the internal name of the unit to your table.
  • Search for the units you wish to modify in the Zero-K repository.
  • Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
  • Base64 encode your table.
  • Put the base 64 encoding of your table into the Tweak Units modoption.
  • Start the game.
  • Check infolog.txt in your install directory and fix your syntax errors.

Check out the unit def and weapon def pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.

Limitations[edit]

Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

Simple Example[edit]

In this example we make Glaive faster and cheaper.

Start with an empty Lua table.

{
}

A search through the unitdef repository reveals that Glaive is known as cloakraid internally. This is the file. Add an empty table with key 'cloakraid'.

{
    cloakraid = {},
}

The SpringRTS wiki page on unitdefs says that a unit's cost is 'metalCost' and its speed is just 'speed'. The Glaive file shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:

{
    cloakraid = {
        metalCost = 50,
        speed = 240,
    },
}

Copy this text into a base64 encoder and click encode. Here is the resulting encoding. ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1ldGFsQ29zdCA9IDUwLAogICAgICAgIHNwZWVkID0gMjQwLAogICAgfSwKfQ== Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.

[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption        <------
[f=-000001] Loading tweakunits for cloakraid    <------
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts

Advanced Example[edit]

In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the Bandit's file and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.

{
    cloakraid = {
        metalCost = 50,
        speed = 240,
    },
    shieldraid = {},
}

Weapon parameters can be found in the SpringRTS page on weapon defs, and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.

{
    cloakraid = {
        metalCost = 50,
        speed = 240,
    },
    shieldraid = {
        weaponDefs = {
            LASER = {
                range = 600,
                damage = {
                    default = 50,
                },
            },
        },
    },
}

As before, we now take this text, base64 encode it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding. e2Nsb2FrcmFpZD17bWV0YWxDb3N0PTUwLHNwZWVkPTI0MCx9LHNoaWVsZHJhaWQ9e3dlYXBvbkRlZnM9e0xBU0VSPXtyYW5nZT02MDAsZGFtYWdlPXtkZWZhdWx0PTUwLH0sfSx9LH0sfQ==

Mass post-processing[edit]

The above examples deal with specific values for a single unit (e.g. "make Glaive have 240 speed"). It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:

for name, ud in pairs(UnitDefs) do
	if ud.speed then
		ud.speed = ud.speed*10
	else
		ud.health = ud.health*5
	end

	if ud.metalcost then
		ud.metalcost = ud.metalcost*2
	end
end

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE (notice how it's metalcost and not metalCost!). This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics, and makes all units twice as expensive. Some fields may be nil (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

Zk 1 7 11 0 cover.jpg