Class Option

Base class for Trimmer Options.

Inheritance

System.Object

Option

OptionContainer

Option<TValue>

Namespace: sttz.Trimmer

Assembly: Trimmer.dll

Syntax

public abstract class Option

Remarks

Options are the basic building blocks to integrate your project into Trimmer. Trimmer detects all Option classes in your project, so there's no additional configuration necessary besides adding the Option source files to your project.

Each Option has a value, which you can edit in the editor and which can also be changed in the player using the RuntimeProfile. The runtime profile is only a script API, use the bundled Options to change Option values in the player using configuration files (OptionIniFile) or a simple GUI (OptionPrompt).

Options can model more complicated data than simple values in two ways:

• Variant Options allow to have multiple instances of the same Option type that differ by their VariantParameter, e.g. to have a volume Option, which can control multiple channels.
• Child Options allow Options to group multiple different values together.

To make an Option variant, set its Variance. To add child Options, define Option classes nested inside other Option classes.

Most of the time, you want to extend one of the typed base classes that fit the type of Option you want to create:

• OptionAsset<TUnity>
• OptionContainer
• OptionEnum<TEnum>
• OptionFloat
• OptionInt
• OptionString
• OptionToggle

Constructors

Option()

Main constructor.

Declaration

public Option()

Remarks

All Option classes need to have a constructor with no arguments.

Caution

Don't override this constructor to initialize your Option subclass. Override Configure() instead.

Fields

changed

Used to track if Option values have changed when editing.

Declaration

public static bool changed

Field Value

Type	Description
System.Boolean

DEFINE_PREFIX

Prefix for the Trimmer scripting defines symbols.

Declaration

public const string DEFINE_PREFIX = "TR_"

Field Value

Type	Description
System.String

Remarks

Conditional compilation defines with this prefix are considered managed by Trimmer. All symbols with this prefix will be removed before a build starts and Options need to re-define their symbols in GetScriptingDefineSymbols(OptionInclusion, HashSet<String>).

OPTION_PREFIX

Prefix applied after the DEFINE_PREFIX for the Option scripting define symbols.

Declaration

public const string OPTION_PREFIX = "Option"

Field Value

Type	Description
System.String

Properties

ApplyOrder

Control the order Options' Apply() methods get called.

Declaration

public int ApplyOrder { get; protected set; }

Property Value

Type	Description
System.Int32

Remarks

Lower values get called first.

Capabilities

The capabilities of the Option.

Declaration

public OptionCapabilities Capabilities { get; }

Property Value

Type	Description
OptionCapabilities

Remarks

Used to cache the attribute value. To change the capabilities, use the CapabilitiesAttribute.

Note

This property is only available in the editor.

Note

This property only applies to main Options. Child and variant Options will inherit the capabilities from their main parent.

Category

Category of the Option.

Declaration

public string Category { get; protected set; }

Property Value

Type	Description
System.String

Remarks

The category is used to group options in the editor.

Note

This property only applies to main Options. Child and variant Options will inherit the category from their main parent.

Children

The children of this Option.

Declaration

public IEnumerable<Option> Children { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<Option>

Remarks

Child Options are nested classes of the current Option class. They are detected automatically and instantiated when their parent Option is instantiated.

HasChildren

Wether this Option has children.

Declaration

public bool HasChildren { get; }

Property Value

Type	Description
System.Boolean

IsDefaultVariant

Wether this option instance is the default variant.

Declaration

public bool IsDefaultVariant { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

Variant options can have an arbitrary number of instances, each with a different variant parameter to distinguish them. Variant options are created on-demand when a new parameter appears. However, the one instance using the VariantDefaultParameter is guaranteed to always exist and acts as container for the other variants.

AddVariant(String), GetVariant(String, Boolean) and RemoveVariant(Option) can only be called on the default variants.

Name

The name of the Option.

Declaration

public string Name { get; protected set; }

Property Value

Type	Description
System.String

Remarks

The name is used in the editor, to identify the option in config files and to set the Option's scripting define symbols.

By default, the name is the Option's class name, minus the OPTION_PREFIX. This ensures that the scripting define symbol set for the Option matches its class name.

In case you set the name to something that doesn't start with the Option prefix, the prefix will be prepended to the Option's scripting define symbol.

e.g.

Class Name	→ Option Name	→ Scripting Define Symbol
OptionExample	→ Example	→ OptionExample
NonDefaultExample	→ NonDefaultExample	→ OptionNonDefaultExample

Parent

The Option containing this option (if any).

Declaration

public Option Parent { get; set; }

Property Value

Type	Description
Option

Remarks

In case of variant Options, the parent is set to the main variant that contains all other variants.

In case of child Options and the main variant, the parent is set to the Option containing the child / main variant.

The parent is null for main Options.

Path

The path to this Option.

Declaration

public string Path { get; }

Property Value

Type	Description
System.String

PostprocessOrder

The priority of the Option's processing callbacks.

Declaration

public int PostprocessOrder { get; protected set; }

Property Value

Type	Description
System.Int32

Remarks

This determines the order in which all Option's processing callbacks are called (PostprocessScene(Scene, OptionInclusion), PrepareBuild(BuildPlayerOptions, OptionInclusion), PreprocessBuild(BuildTarget, String, OptionInclusion) and PostprocessBuild(BuildTarget, String, OptionInclusion)).

Lower values will be called first.

Warning

This only orders the Options between themselves. This does not affect the order in regard to other consumers of these Unity events.

Note

This property is only available in the editor.

Note

This property only applies to main Options. Child and variant Options will inherit the order from their main parent.

SupportedTargets

The BuildTargets this Option supports. (null = all)

Declaration

public IEnumerable<BuildTarget> SupportedTargets { get; protected set; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<UnityEditor.BuildTarget>

Remarks

Note

This property is only available in the editor.

Note

This property only applies to main Options. Child and variant Options will inherit the supported targets from their main parent.

Variance

The variance of the Option.

Declaration

public OptionVariance Variance { get; protected set; }

Property Value

Type	Description
OptionVariance

Remarks

By default, an Option is invariant and there's only a single instance / value of it.

An Option can also be variant, in which case multiple instances can exist and the instances are distinguished by their VariantParameter.

There are two types of variance, where the only difference is if their parameters are set by the user (Dictionary) or if an index is assigned automatically as parameter (Array).

Variant Options have a default variant (IsDefaultVariant), that acts as the container for all other variants and its parameter is always set to the VariantDefaultParameter.

VariantDefaultParameter

The parameter of the default variant.

Declaration

public string VariantDefaultParameter { get; protected set; }

Property Value

Type	Description
System.String

Remarks

Variants are created on-demand when new parameters appear. To ensure the Option can always receive callbacks, a single Option is always guaranteed to exist and that Option uses the variant default parameter.

VariantParameter

The parameter of a variant Option.

Declaration

public string VariantParameter { get; set; }

Property Value

Type	Description
System.String

Remarks

The parameter is only used when Variance is not Single.

When Variance is Array, the parameter is assigned automatically and will be overwritten if it's changed.

Variants

The variants contained in the default variant.

Declaration

public IEnumerable<Option> Variants { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<Option>

Remarks

Only the IsDefaultVariant Option can contain variants. All other Options return an empty enumerable.

The enumerable does not contain the default variant itself.

Methods

AddVariant(String)

Add a new variant option.

Declaration

public Option AddVariant(string parameter)

Parameters

Type	Name	Description
System.String	parameter

Returns

Type	Description
Option

Remarks

Warning

This method can only be called on default variants, where IsDefaultVariant is true, and will throw an exception when called on other Options.

Tip

For array variants, the parameter can be assigned arbitrarily and will be overwritten on insertion. However it can be used to control where the variant will be inserted, as parameters will be first sorted before the indices are re-assigned (e.g. inserting "5.5" will insert the variant between "5" and "6").

Apply()

Apply the Option to the current environment.

Declaration

public virtual void Apply()

Remarks

This method is called when the Option should act on its value.

This is when the game is started in the editor or in a player, or when the Option's value is changed while the game is playing.

Main Options as well as its children and variants are applied together. E.g. when the main Option's or one of its children's value is changed, all of their Apply methods will be called.

This method does not get called when scenes change. Use Unity's SceneManager callbacks to get notified when scenes get loaded and unloaded or the active scene changes.

ApplyFromRoot()

Look for the root Option and then call its Apply() method.

Declaration

public void ApplyFromRoot()

ClearVariants()

Remove all variant Options.

Declaration

public void ClearVariants()

Remarks

Warning

This method can only be called on default variants, where IsDefaultVariant is true, and will throw an exception when called on other Options.

Configure()

Configure the Option instance during instantiation.

Declaration

protected virtual void Configure()

Remarks

Override this method instead of the constructor to configure your Option instance. Most Option properties should only bet set once in this method and then not changed after the Option is created.

CreateChildren()

Internal helper method to create the child Option instances.

Declaration

protected void CreateChildren()

EditGUI()

Do the editor GUI to edit this option.

Declaration

public abstract bool EditGUI()

Returns

Type	Description
System.Boolean

Remarks

The bundled subclasses in sttz.Trimmer.BaseOptions already provide implementations for this method. Override it to implement your custom GUI for the editor.

Note

This method is only available in the editor.

GetChild(String)

Get a child Option by its name.

Declaration

public Option GetChild(string name)

Parameters

Type	Name	Description
System.String	name

Returns

Type	Description
Option

GetChild<TOption>()

Get a child Option instance by its type.

Declaration

public TOption GetChild<TOption>()
    where TOption : Option

Returns

Type	Description
TOption

Type Parameters

Name	Description
TOption

GetPathRecursive(Option)

Internal helper method to construct an Option's path recursively.

Declaration

protected string GetPathRecursive(Option current)

Parameters

Type	Name	Description
Option	current

Returns

Type	Description
System.String

GetScriptingDefineSymbols(OptionInclusion, HashSet<String>)

The scripting define symbols set by this Option.

Declaration

public virtual void GetScriptingDefineSymbols(OptionInclusion inclusion, HashSet<string> symbols)

Parameters

Type	Name	Description
OptionInclusion	inclusion
System.Collections.Generic.HashSet<System.String>	symbols

Remarks

By default, this method will define

DEFINE_PREFIX + OPTION_PREFIX + Name

if the Option is included and

DEFINE_PREFIX + Name

if the associated feature is included.

Only the main Option will set these symbols but child and variant Options can set additional symbols.

Note

This method is only available in the editor.

GetVariant(String, Boolean)

Get the variant Option with the given parameter.

Declaration

public Option GetVariant(string parameter, bool create = true)

Parameters

Type	Name	Description
System.String	parameter
System.Boolean	create	Wether a new variant should be created if one doesn't currently exist

Returns

Type	Description
Option

Remarks

Warning

This method can only be called on default variants, where IsDefaultVariant is true, and will throw an exception when called on other Options.

GetVariant can also be used to get the default variant itself, i.e. when parameter equals VariantDefaultParameter, the method will return this.

InvalidatePathRecursive()

Internal helper method to invalidate all child/variant Option's paths recursively.

Declaration

public void InvalidatePathRecursive()

IsAvailable(IEnumerable<BuildTarget>)

Determines if the Option is available on one of the given build targets.

Declaration

public virtual bool IsAvailable(IEnumerable<BuildTarget> targets)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<UnityEditor.BuildTarget>	targets

Returns

Type	Description
System.Boolean

Remarks

It's possible to hide an Option in Build Profiles if they don't apply to the profile's build targets (i.e. an iOS-only Option on an Android Build Profile). Unavailable Options can be shown using an Option in Trimmer's preferences but they will always be removed from builds.

Note

This method is only available in the editor.

Note

This method only applies to main Options. Child and variant Options will inherit the availability from their main parent.

Load(String)

Parse and load an input string.

Declaration

public abstract void Load(string input)

Parameters

Type	Name	Description
System.String	input

Remarks

This method is called with the value defined in the profile or entered by the user. This method should parse the input and then save it to Value. If the input is empty or contains an invalid value, the DefaultValue should be used instead.

Load should only parse the value but not yet apply it to the project. Use Apply() to act on the Option's value.

PostprocessBuild(BuildTarget, String, OptionInclusion)

Callback invoked after the build completed.

Declaration

public virtual void PostprocessBuild(BuildTarget target, string path, OptionInclusion inclusion)

Parameters

Type	Name	Description
UnityEditor.BuildTarget	target	Build target type
System.String	path	Path to the built project
OptionInclusion	inclusion	Wether this option is included in the build

Remarks

This callback is invoked after the build has been completed, for both profile builds and regular Unity builds.

Note

This method is only available in the editor.

PostprocessScene(Scene, OptionInclusion)

Callback invoked for every scene during build.

Declaration

public virtual void PostprocessScene(Scene scene, OptionInclusion inclusion)

Parameters

Type	Name	Description
UnityEngine.SceneManagement.Scene	scene	The scene that is being processed.
OptionInclusion	inclusion	Wether the option is included in the build.

Remarks

This callback gives Options a chance to modify scenes during the build process. This can be used to e.g. inject a script into the scene or remove some game objects.

Unlike Unity's OnProcessScene, this method is not called when playing in the editor. Use Apply() and Unity's SceneManager API instead.

Note

This method is only available in the editor.

PrepareBuild(BuildPlayerOptions, OptionInclusion)

Callback invoked before a profile build is started.

Declaration

public virtual BuildPlayerOptions PrepareBuild(BuildPlayerOptions options, OptionInclusion inclusion)

Parameters

Type	Name	Description
UnityEditor.BuildPlayerOptions	options	The current options
OptionInclusion	inclusion	Wether the Option is included in the build.

Returns

Type	Description
UnityEditor.BuildPlayerOptions	The modified options.

Remarks

When a build is started on a BuildProfile, all options will receive this callback before the build is started.

This callback allows Option to influence the build settings, including build options, output path and included scenes.

By default, the build will include the scenes set in Unity's build player window and the options will be set to BuildOptions.None. If no Option sets the location path name, the user will be prompted to choose it.

Warning

This method will not be called for regular Unity builds, started from the build player window or using the build menu item.

Note

This method is only available in the editor.

PreprocessBuild(BuildTarget, String, OptionInclusion)

Callback invoked right before a build.

Declaration

public virtual void PreprocessBuild(BuildTarget target, string path, OptionInclusion inclusion)

Parameters

Type	Name	Description
UnityEditor.BuildTarget	target	Build target type
System.String	path	Path to the built project
OptionInclusion	inclusion	Wether this option is included in the build

Remarks

This callback is invoked before the build, for both profile builds as well as regular Unity builds.

Note

This method is only available in the editor.

RemoveVariant(Option)

Remove a variant Option.

Declaration

public void RemoveVariant(Option option)

Parameters

Type	Name	Description
Option	option

Remarks

Warning

This method can only be called on default variants, where IsDefaultVariant is true, and will throw an exception when called on other Options.

RenumberArrayVariants()

Internal helper method that ensures parameters in array variants are all numbers and sequential.

Declaration

protected void RenumberArrayVariants()

Save()

Serialize the Option's value to a string.

Declaration

public abstract string Save()

Returns

Type	Description
System.String

Remarks

The value returned by this method will later be supplied to Load(String) and should survive the round-trip without loss.

ShouldIncludeOnlyFeature()

Determines if the inclusion of the associated feature should be overridden in case only the feature is included but isn't properly configured or enabled.

Declaration

public virtual bool ShouldIncludeOnlyFeature()

Returns

Type	Description
System.Boolean

Remarks

This method is only called if the Option has an associated feature and only if the feature is included but the Option is not.

The method allows the Option to check if the feature is properly configured and only include it if it is. Since only the feature is included and the Option is not, it's potentially not possible to properly configure the feature in the build and therefore it makes no sense to include it.

Returning false will change the inclusion from Feature to Remove.

Note

This method is only available in the editor.

Note

This method only applies to main Options. Child and variant Options will inherit the inclusion from their main parent.