Class ConfigLayoutDefinition

The serializable form of a ConfigLayout: an input configuration screen's columns, groups and exclusion sets, authored as data rather than as code.

Inheritance

object

ConfigLayoutDefinition

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Input

Assembly: ScyllaInput.dll

Syntax

[Serializable]
public class ConfigLayoutDefinition

Remarks

ConfigLayout can only be built through its fluent builder, which means a game's controls screen has had to hard-code its layout in C#. This type is the same model in a form Unity can serialize, so the layout becomes authored data that an editor can edit and validate.

The builder is still the only construction path. ToConfigLayout(IReadOnlyList<InputContext>) feeds it rather than bypassing it, so the builder's own validation cannot be sidestepped and the two ways of declaring a layout cannot drift apart.

Validate(IReadOnlyList<string>, IReadOnlyList<string>, IReadOnlyList<string>) is a strict superset of everything the builder throws on. A definition that validates clean is guaranteed to build, which is what lets an editor report problems in a list instead of surfacing an exception.

Fields

Columns

The columns, in display order.

Declaration

[Tooltip("The columns, in display order.")]
public List<ConfigLayoutColumnDefinition> Columns

Field Value

Type	Description
List<ConfigLayoutColumnDefinition>

DeriveExclusionsFromContexts

Whether to additionally derive exclusion sets from the conflict-exclusive tags authored on the game's input contexts.

Declaration

[Tooltip("Also derive exclusion sets from the conflict-exclusive tags authored on the input contexts.")]
public bool DeriveExclusionsFromContexts

Field Value

Type	Description
bool

Exclusions

The exclusion sets.

Declaration

[Tooltip("The exclusion sets.")]
public List<ConfigLayoutExclusionDefinition> Exclusions

Field Value

Type	Description
List<ConfigLayoutExclusionDefinition>

Groups

The groups, in display order.

Declaration

[Tooltip("The groups, in display order.")]
public List<ConfigLayoutGroupDefinition> Groups

Field Value

Type	Description
List<ConfigLayoutGroupDefinition>

Properties

IsEmpty

Gets whether nothing has been authored yet.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool

Methods

FromDocument(InputActionsDocument)

Builds a default layout from an action asset: one column per control scheme and one group per action map.

Declaration

public static ConfigLayoutDefinition FromDocument(InputActionsDocument document)

Parameters

Type	Name	Description
InputActionsDocument	document	The parsed action asset.

Returns

Type	Description
ConfigLayoutDefinition	A definition mirroring the asset's own structure.

Remarks

This is the cold-start path. It means a configuration screen, and an editor showing one, works against a vanilla Unity asset with no Scylla authoring at all, which is what stops the feature having a chicken-and-egg problem.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the document is null.

ToConfigLayout(IReadOnlyList<InputContext>)

Materializes the runtime layout, resolving membership from the cached names.

Declaration

public ConfigLayout ToConfigLayout(IReadOnlyList<InputContext> contexts = null)

Parameters

Type	Name	Description
IReadOnlyList<InputContext>	contexts	The registered contexts, used only when DeriveExclusionsFromContexts is set. Passing null is not an error and derives nothing. A caller holding a manager passes GetAllContexts(); a caller holding only the configuration asset, such as an editor, builds the list from its definitions.

Returns

Type	Description
ConfigLayout	The built layout.

Remarks

This is the runtime path, used by a shipped game that has the authored asset but no parsed document in memory. Names are taken as they were at last sync, which is why they are stored rather than derived.

Exceptions

Type	Condition
InvalidOperationException	Thrown when no column is declared.
ArgumentException	Thrown when the declaration is malformed.

ToConfigLayout(IReadOnlyList<InputContext>, InputActionsDocument)

Materializes the runtime layout, resolving membership against a parsed document so a map or action renamed since the last sync still resolves.

Declaration

public ConfigLayout ToConfigLayout(IReadOnlyList<InputContext> contexts, InputActionsDocument document)

Parameters

Type	Name	Description
IReadOnlyList<InputContext>	contexts	The registered contexts, used only when DeriveExclusionsFromContexts is set. Passing null is not an error and derives nothing. A caller holding a manager passes GetAllContexts(); a caller holding only the configuration asset, such as an editor, builds the list from its definitions.
InputActionsDocument	document	The parsed action asset used to resolve GUIDs to current names, or null to use the cached names.

Returns

Type	Description
ConfigLayout	The built layout.

Exceptions

Type	Condition
InvalidOperationException	Thrown when no column is declared.
ArgumentException	Thrown when the declaration is malformed.

TryToConfigLayout(IReadOnlyList<InputContext>, InputActionsDocument, out ConfigLayout, out string)

Attempts to materialize the runtime layout, reporting failure rather than throwing.

Declaration

public bool TryToConfigLayout(IReadOnlyList<InputContext> contexts, InputActionsDocument document, out ConfigLayout layout, out string error)

Parameters

Type	Name	Description
IReadOnlyList<InputContext>	contexts	The registered contexts, or null.
InputActionsDocument	document	The parsed action asset, or null.
ConfigLayout	layout	The built layout on success, otherwise null.
string	error	A description of the failure on failure, otherwise null.

Returns

Type	Description
bool	true when the layout was built.

Validate(IReadOnlyList<string>, IReadOnlyList<string>, IReadOnlyList<string>)

Checks the definition against the action asset's own contents.

Declaration

public List<ConfigLayoutValidationMessage> Validate(IReadOnlyList<string> knownMapNames, IReadOnlyList<string> knownActionNames, IReadOnlyList<string> knownBindingGroups)

Parameters

Type	Name	Description
IReadOnlyList<string>	knownMapNames	Every action map name in the asset, or null to skip those checks.
IReadOnlyList<string>	knownActionNames	Every action name in the asset, or null to skip those checks.
IReadOnlyList<string>	knownBindingGroups	Every binding group declared by a control scheme, or null to skip those checks.

Returns

Type	Description
List<ConfigLayoutValidationMessage>	Every problem found, empty when the definition is sound.

Remarks

Every rule here corresponds to something that throws later, either in the builder or in Initialize(ConfigLayout). A clean result therefore guarantees ToConfigLayout(IReadOnlyList<InputContext>) succeeds, which is the contract an editor relies on to show problems in a list rather than as an exception.

See Also

ConfigLayout