Setting up your Mod for tweaking

How the Mod Tweaker works

The tweaking works on a per-ModOp level. The Tweaker

• creates a new file <filename>.imyatweak.include.xml
• copies the entire ModOp to a seperate file
• modifies the value of the copy with an expose instruction
• skips the original ModOp in the original file
• includes the new file in the end of your original file

Because changes are only done to the copy, not to the original, this means you can use the Tweaker for all XML files at the moment, presuming you are using ModOps in it. The modloader does the rest for us.

Values you edited are stored locally in .imya/tweaks in your game folder.

How to expose a value?

Set up your ModOp for tweaking

Simply add a ModOpID Attribute to your modop, like this:

<ModOp Path="/TextExport/Texts" Type="add" ModOpID="HeaterText" Skip="1">
  <Text>
    <GUID>8857100</GUID>
    <Text>Gas Heater</Text>
  </Text>
</ModOp>

Create a simple expose instruction

1. Create an ImyaExpose node in your document, like you would normally create a ModOp.
2. Give your ImyaExpose node a unique (!!) ID, in the Attribute ExposeID. This ID will be used for saving the value.

Do not change the ExposeID when distributing an update to your mod, or all tweaks users make will be lost on their side.

3. Link your ImyaExpose to the Modop, by specifying the ModOpID this Expose should apply to.

One expose can link to multiple modops, just as multiple exposes can target the same ModOpID.

4. Add a Path to the ImyaExpose to select XML nodes on the ModOp level, just as you would write a path for a ModOp using xPath.

The value change done by the user will be applied to all nodes selected by this Path.

The resulting expose instruction might look something like this for you:

<ImyaExpose Path="self::Text/Text" ModOpID="HeaterText" ExposeID="HeaterText" />

If you did everything correctly, it should show up like this in the mod tweaker:

Descriptions

If you want to add a description to be shown, you can add a Description attribute to your ImyaExpose node.

Best Practice Guidelines

Instead of selecting a value with a complex path, make a seperate ModOp that you use for exposing. This will minimize the amount of code overwritten by the Tweaker and only change what you need to change.

<ModOp GUID="8857100" Type="replace" Path="/Values/Maintenance/Maintenances/Item[Product='1010017']/Amount" ModOpID="Heater">
    <Amount>90</Amount>
</ModOp>
<ImyaExpose Path="self::Amount" ModOpID="Heater" ExposeID="CreditMaintenance" />

Skips and Includes are Automatically added to your file. You do not need to do anything regarding this. This is only done once there are actual tweaks being generated.

Advanced Expose Instructions

Since editing in text fields might not always be the preferred choice, imya offers a variety of different expose instructions.

Enumerations

An enumeration allows the user to select from a few predefined options in a ComboBox control.

1. Add Kind="Enum" as an Attribute to your ImyaExpose Node
2. Add a FixedValues node inside
3. Add the predefined values into FixedValues in nodes called Value

Code sample:

<ImyaExpose Path="self::CycleTime" ModOpID="HeaterCycleTime" ExposeID="CycleTime" Description="The Heaters Production Time in Seconds" Kind="Enum">
  <FixedValues>
    <Value>30</Value>
    <Value>60</Value>
    <Value>90</Value>
    <Value>120</Value>
  </FixedValues>
</ImyaExpose>

Sliders

A slider is useful for when you want a value to be tweaked in a certain range.

1. Add Kind="Slider" to your ImyaExpose node as an attribute
2. Add a SliderDefinition node inside the ImyaExpose
3. Specify the Min, Max and Stepping Attributes on the SliderDefinition node

Min & Max should be obvious. Stepping controls the granularity with which the value can be tweaked.

Code sample

<ImyaExpose Path="self::HeatRange" ModOpID="HeaterRange" ExposeID="HeaterRange" Description="The Range of the Gas Heater in Tiles" Kind="Slider">
  <SliderDefinition Min="20" Max="40" Stepping="1" />
</ImyaExpose>

Toggles

Despite looking like a simple On-/Off switch (okay, it is one), toggles are immensely powerful, since you can also modify XML code through them.

1. Add Kind="Toggle" to your ImyaExpose node as an attribute
2. Add an AltValue node inside.
3. Add alternative XML into your AltValue node.

Toggle logic:

• On: Original ModOp code gets used.
• Off: AltValue code gets used.

Code sample:

<ImyaExpose Path="." ModOpID="HeaterPausable" ExposeID="HeaterPausable" Description="Sets whether the Heater can be paused in the menu" Kind="Toggle">
  <AltValue>
    <ThisIsATotallyDifferentNode>Proof that I replaced the node</ThisIsATotallyDifferentNode>
  </AltValue>
</ImyaExpose>

The difference hopefully becomes clearer using this example:

First the original modop:

<ModOp GUID="8857100" Type="replace" Path="/Values/Pausable/CanPauseManually" ModOpID="HeaterPausable" Skip="1">
  <CanPauseManually>1</CanPauseManually>
</ModOp>

And here is the generated result when using the AltValue.

<ModOp Path="/Values/Pausable/CanPauseManually" GUID="8857100" Type="replace">
  <ThisIsATotallyDifferentNode>Proof that I replaced the node</ThisIsATotallyDifferentNode>
</ModOp>

If the toggle is true, the generated result will of course equal the original.

Titles

To set a title for your file, use <ImyaTweaks Title="YourTitle" /> on ModOp level