Easy Tweak - User Guide

 

Overview

Easy Tweak is a scripting tool that lets you create in-game tweaks and options within seconds. By adding a simple attribute to the properties, fields or methods in your script, you get the 'GUI' controls that lets you easily tweak and test different settings in the game build, eliminating the need to rebuild and redeploy the game to the device.

Requirement

Since EasyTweak uses some of the reflection features that older versions of C# does not support, you may need to adjust your scripting runtime version settings in your Player Settings.

For Unity 2017:

For Unity 2018 and Unity 2019

Quick Start

  1. Drag the EasyTweakManager prefab to your scene. Note that you should have one and only one EasyTweakPrefab per scene.

  2. Add an EasyTweak component with the "Add Component" button to the GameObject that contains the script that you want to tweak.

    Note: A GameObject can have multiple scripts that contains the [EasyTweak] attribute, while only one EasyTweak component is needed per GameObject.

  3. In your script (MonoBehaviour), add an [EasyTweak] attribute to each property or field that you want to control or monitor with Easy Tweak, or to each method that you want to call. Add using EasyTweak; to the file if needed.

And that's all the setup you need to use EasyTweak. Now in your builds, you can activate the EasyTweak window and tweak the values or invoke the methods easily. You can also create presets and test different combinations, undo or reset all your changes with only a few taps/clicks.

For an example setup, please check the included demo scene.

The [EasyTweak] Attribute

Basic Usage

There is only one single attribute you need to use in your script when working with EasyTweak, that is:

[EasyTweak]

For example,

will produce a input field:

image-20200203012010873

Another example:

will produce a button:

image-20200203012305733

Note that a label string is provided here. This will be used as the display name of the UI control. If the string provided is an empty string or not provided at all, the name of the member in the script will used.

Supported Members

The [EasyTweak] attribute can be added to the following types of members of a script:

For properties and fields, the supported types are:

Types that are not supported will be displayed as a string.

Labels

A label text will be used as the display name if provided when using the [EasyTweak] attribute. If an empty label is provided or not provided at all, the name of the variable in the script will be used.

Groups

A group string can also be provided to the [EasyTweak] attribute. Members with the same group string will be grouped together to better organize your control.

For example:

will produce:

image-20200203095010734

Value Sliders

For numeric types such as int, float, etc., provide a 'sliderMin' and a 'sliderMax' value to the will turn the UI to a slider instead of an input field.

For example:

will produce:

image-20200203095250543

Colors and Color Picker

EasyTweak support Unity's Color structs as monitored members. A Color property or field will produce a color control similar to Unity editor.

For example:

will produce:

image-20200203095702392

You can also click/tap the color display to open a color picker similar to Unity editor's color picker.

image-20200203100050051

Read-only Controls

If you provide a 'true' boolean to the [EasyTweak] attribute, the control will be read-only. This is useful if you want to monitor a variable but do not want to modify it by hand.

For example:

will produce:

image-20200203101328758

Properties without a setter will be read-only as well.

Activating the Easy Tweak Window

The Easy Tweak Window is the place where you perform most of the operations with Easy Tweak. It will be hidden and does not actually build any UI interface when the scene is loaded, minimizing the effect to the scene's loading time.

By default, you can activate the EasyTweak windows using the methods described below.

For desktop builds, Unity Editor or any device that has a mouse:

For mobile devices or any device that has a touch screen:

The activation method can be changed using the EasyTweakManager in your scene.

Working with the Easy Tweak Window

After you have performed one of the activation method listed above, the Easy Tweak Window will be displayed. For example:

image-20200203000914137

All the scripts in the scene that have the [EasyTweak] attribute will be managed in a single Easy Tweak Window, and organized by the script instances. For example, if you have two GameObjects that both contain the same script, the two scripts will be put into separate sections in the Easy Tweak Window.

Using the EasyTweak Window is pretty straight-forward: All your properties, fields or methods on which you added the [EasyTweak] attribute will be listed. From here, you can tweak the values or call different methods to test different settings for your game.

Dragging and Resizing the window

The Easy Tweak Window can be dragged by its title bar:

image-20200203003614965

To scale up/down the window for a better view, drag the triangle area in the bottom right: image-20200203003658685

To change the height of the window, drag the bottom status bar (the one that displays the FPS and Total Monitored Members).

image-20200203003730521

Pinning and Unpinning UI Controls

Since all the class members with the [EasyTweak] attribute are managed in the same window, sometimes it's more convenient to focus only a few of them that you are interested in instead of looking at the whole panel. For this purpose, EasyTweak lets you pin the UI controls individually to separate them from the main window.

To pin a UI control, simply click the pin buttonimage-20200203005017597 to the right of each UI control.

To unpin a UI control, use the unpin button image-20200203005331302 of the pinned UI control.

Undo and Redo

To undo or redo a change you made, use the buttons below the title bar:

image-20200203091411298

Note that you cannot undo the changes made by the method calls (i.e. "buttons").

Change Summary

EasyTweak allows you to get a summary of all the changed values from their default values. To show the summary panel, press the Summary button image-20200203092031424.

image-20200203092223000

Note that read-only members will not be included in the summary.

You can refresh this view by pressing the Refresh button.

Using Presets

Presets are basically snapshots of your current settings for a certain MonoBehaviour. This is very useful to track and compare different settings to decide which combination of the settings are better.

To create a preset with the current settings, use the Preset button image-20200203092745544 to the end of each section. (Note that the scope of a preset is MonoBehaviour, meaning that you need to create multiple presets to record settings for different MonoBehaviours).

image-20200203093429747

Note #1: Read-only members will not be recorded into a preset.

Note #2: Preset will not be saved on WebGL players. You can still create presets and use them like normal, except they will not be preserved after you close or reload the webpage.

Reset All Changes of a Script

The Reset All buttonimage-20200203093637780 will reset all the changes you made to a certain MonoBehaviour to their default values. You can also undo the reset with the Undo button.

Reset Individual UI Controls

To reset a value for a certain UI control, simply double click/tap it label.

Performance Tips

Although EasyTweak uses C# reflection to get the values from the variables, it is still quite fast and only have minimal effect to your game's performance. This is because the EasyTweak main window will only refresh the UI controls that is visible on the screen. If a UI control is hidden by the scroll view, it will stop updating its values until it is visible again.

However, the corresponding UI controls will still be created for each controlled member, and that will probably become a performance bottleneck if you have a couple hundreds of them.

So generally it is perfectly OK to have any number of controlled class members as long as your machine can handle it, just bare in mind that it may effect the performance if you have too many of them.

Additionally, the UI controls in the main window will not update at all if the main window is closed.


For help, feature suggestions and bug reports, contact me at lx84@outlook.com. For more information about the plugin and my other work, please visit https://www.mkstudio.xyz/assets.html.

Copyright © 2020 MK Studio. All rights reserved.