Class ScyllaModulePlacement

Static utility class for validating and reporting the correct placement of Scylla module GameObjects within the Unity scene hierarchy.

Inheritance
object
ScyllaModulePlacement
Inherited Members
Namespace: Scylla.Core.Modules
Assembly: ScyllaCore.dll
Syntax
public static class ScyllaModulePlacement
Remarks

The Scylla module system enforces a strict scene hierarchy rule: every module UnityEngine.GameObject must be a direct child of the ScyllaBootstrap root UnityEngine.GameObject. Grandchildren and deeper descendants are not permitted as module hosts. This constraint exists so that the framework can discover modules reliably by iterating the immediate children of the bootstrap root, and so that module lifetime is fully controlled by Unity's scene graph rather than by parenting to arbitrary objects.

This class does not perform any registration or lifecycle operations - it is purely a validation and diagnostic helper. Placement validation typically occurs inside Awake() (or whichever base-class hook calls IsDirectChildOfRoot(Transform, Transform)) and produces a fatal error via BuildInvalidPlacementMessage(string, string, string, string, Transform) if the constraint is violated.

Methods

BuildInvalidPlacementMessage(string, string, string, string, Transform)

Constructs a human-readable, actionable error message describing a module placement violation, including an ASCII tree illustration of the required hierarchy structure.

Declaration
public static string BuildInvalidPlacementMessage(string moduleName, string moduleID, string moduleGameObjectName, string scyllaRootGameObjectName, Transform actualParent)
Parameters
Type Name Description
string moduleName

The human-readable name of the module (e.g. "ScyllaInput"). If null or empty, the placeholder "<unknown module>" is used.
string moduleID

The unique identifier of the module (e.g. "ScyllaInput"). If null or empty, the placeholder "<unknown id>" is used.
string moduleGameObjectName

The name of the module's UnityEngine.GameObject as it appears in the Unity Hierarchy window. If null or empty, the placeholder "<unnamed>" is used.
string scyllaRootGameObjectName

The name of the ScyllaBootstrap root UnityEngine.GameObject that the module must be a direct child of. If null or empty, the placeholder "<unnamed>" is used.
Transform actualParent

The actual parent UnityEngine.Transform of the module at the time of the violation. Used to show the developer where the module currently sits. Pass null if the module has no parent (i.e., it is at the scene root), in which case the message displays "<no parent>".
Returns
Type Description
string

A multi-line string containing:

  • A summary of the violation including the module name and ID.
  • The name of the current (incorrect) parent.
  • A step-by-step fix instruction referencing the Unity Hierarchy window.
  • An ASCII tree showing the required parent-child structure.
  • A "Quitting now ..." trailer indicating that the framework has halted.
Remarks

All string parameters are sanitized with null/empty guards before being embedded in the returned message, so this method is safe to call even if module metadata is partially constructed. The message is intended to be passed directly to a fatal logger (e.g. Log.Fatal) or displayed in the Unity Console before the application quits.

See Also

IsDirectChildOfRoot(Transform, Transform)

Determines whether moduleTransform is a direct (immediate) child of scyllaRootTransform in the Unity scene hierarchy.

Declaration
public static bool IsDirectChildOfRoot(Transform scyllaRootTransform, Transform moduleTransform)
Parameters
Type Name Description
Transform scyllaRootTransform

The UnityEngine.Transform of the ScyllaBootstrap root UnityEngine.GameObject that all module GameObjects must be parented to. If null, the method returns false.
Transform moduleTransform

The UnityEngine.Transform of the module UnityEngine.GameObject whose placement is being validated. If null, the method returns false.
Returns
Type Description
bool

true if moduleTransform's immediate parent is scyllaRootTransform; false if either argument is null, if moduleTransform has no parent, or if its parent is any UnityEngine.Transform other than scyllaRootTransform.
Remarks

The check is a single reference equality comparison between moduleTransform.parent and scyllaRootTransform. Grandchildren and deeper descendants of the root will always return false, since their parent is an intermediate transform, not the root itself.

if (!ScyllaModulePlacement.IsDirectChildOfRoot(bootstrap.transform, transform))
{
    var msg = ScyllaModulePlacement.BuildInvalidPlacementMessage(
        Info.Name, Info.ID, gameObject.name, bootstrap.gameObject.name, transform.parent);
    Log.Fatal(msg, LogCategory.Module);
    Application.Quit();
}
See Also

See Also