Game.ToolBaseSystem

Assembly:
Namespace: Game.Tools

Type: abstract class

Base: GameSystemBase, IEquatable

Summary:
ToolBaseSystem is the shared base class for in-game tools (editing/build modes) in Cities: Skylines 2. It centralizes common functionality used by concrete tools: input/action wiring, raycasting setup, brush selection and caching, prefab/infoview handling, entity query helpers, job scheduling helpers for creation/cleanup, and focus/update lifecycle integration with the world systems (ToolSystem, PrefabSystem, ToolRaycastSystem, etc.). It exposes extensibility points for derived tools to define UI modes, available snaps, raycast behavior and how prefabs are selected/applied.

---

Fields

• public const Snap kSnapAllIgnoredMask = Snap.AutoParent | Snap.PrefabType | Snap.ContourLines
  Constant mask describing snap flags that are ignored by default in certain tool logic.

• protected ToolSystem m_ToolSystem
  Reference to the central ToolSystem (manages all tool instances and global tool state).

• protected PrefabSystem m_PrefabSystem
  Reference to the PrefabSystem for looking up prefabs and prefab data.

• protected DefaultToolSystem m_DefaultToolSystem
  Reference to the default tool system.

• protected ToolRaycastSystem m_ToolRaycastSystem
  Reference to the raycast system used by tools to query the world.

• protected OriginalDeletedSystem m_OriginalDeletedSystem
  System used to track original-deleted state checks (used when deciding whether to force updates or allow apply).

• protected EntityQuery m_ErrorQuery
  EntityQuery used to detect errors that block applying tool actions.

• protected Snap m_SnapOnMask
  Snap flags that may be turned on (available) for this tool.

• protected Snap m_SnapOffMask
  Snap flags that may be turned off (disabled) for this tool.

• protected bool m_HasFocus
  Tracks whether this tool currently has UI focus.

• protected bool m_FocusChanged
  Set when focus state changes; used to let derived tools react once.

• protected bool m_ForceUpdate
  Flag set when a forced update of the tool state is required.

• private IProxyAction m_ApplyAction
  Backing field for the apply action proxy (primary apply action).

• private IProxyAction m_SecondaryApplyAction
  Backing field for the secondary apply action proxy.

• private IProxyAction m_CancelAction
  Backing field for the cancel action proxy.

• private protected IProxyAction m_DefaultApply
  Cached default apply action retrieved from the input manager for this tool type.

• private protected IProxyAction m_DefaultSecondaryApply
  Cached default secondary apply action for this tool type.

• private protected IProxyAction m_DefaultCancel
  Cached default cancel action for this tool type.

• private protected IProxyAction m_MouseApply
  Mouse-apply action (mouse button apply).

• private protected IProxyAction m_MouseCancel
  Mouse-cancel action (mouse button cancel).

• private TypeHandle __TypeHandle
  Internal type handle structure used to cache Component/Entity type handles for use in jobs.

• private nested structs: DestroyDefinitionsJob, InvertBrushesJob, TypeHandle
  Burst-compiled job structs used by helper methods such as DestroyDefinitions and InvertBrushes. TypeHandle holds cached ComponentTypeHandle/EntityTypeHandle references used by jobs.

Properties

• public abstract string toolID { get; }
  Unique identifier for the tool (must be provided by derived classes).

• public virtual int uiModeIndex => 0
  Index used for UI mode ordering/presentation. Derived classes can override.

• public virtual Color32 color { get; set; }
  Tool color used for visualization (selection overlays, handles, etc.).

• public BrushPrefab brushType { get; set; }
  Selected brush prefab for painting tools (may be null).

• public float brushSize { get; set; }
  Brush size used by painting tools.

• public float brushAngle { get; set; }
  Brush rotation/angle setting.

• public float brushStrength { get; set; }
  Brush strength/intensity for painting effects.

• public bool requireZones { get; protected set; }
  Tool requirement flag (tool requires city zones to exist / be available).

• public bool requireUnderground { get; protected set; }
  Tool requirement flag for underground elements.

• public bool requirePipelines { get; protected set; }
  Tool requirement flag for pipeline utilities.

• public bool requireNetArrows { get; protected set; }
  Tool requirement flag for network arrows.

• public bool requireStopIcons { get; protected set; }
  Tool requirement flag for stop icons.

• public AreaTypeMask requireAreas { get; protected set; }
  Area type requirements (mask) for the tool.

• public RouteType requireRoutes { get; protected set; }
  Route type requirements for the tool.

• public TransportType requireStops { get; protected set; }
  Transport type requirement for stops.

• public Layer requireNet { get; protected set; }
  Net layer requirement.

• public InfoviewPrefab infoview { get; private set; }
  Optional Infoview prefab associated with the currently selected prefab (or null).

• public List<InfomodePrefab> infomodes { get; private set; }
  List of infomodes available for the selected prefab (populated by UpdateInfoview).

• public virtual Snap selectedSnap { get; set; }
  Currently selected snap mask for the tool (combination of Snap flags).

• public ApplyMode applyMode { get; protected set; }
  Apply mode for the tool (how apply operations are performed — contextual to tool).

• public virtual bool allowUnderground { get; protected set; }
  If true, tool allows placing/working underground.

• public virtual bool brushing => false
  Whether the tool is currently doing continuous brushing (override in brush tools).

• protected IProxyAction applyAction { get; }
  Resolved apply action (returns m_ApplyAction or defaults to m_DefaultApply). Protected convenience accessor.

• protected IProxyAction secondaryApplyAction { get; }
  Resolved secondary apply action.

• protected IProxyAction cancelAction { get; }
  Resolved cancel action.

• protected IProxyAction applyActionOverride { get; set; }
  Override accessor for apply action. Setting to null restores the default.

• protected IProxyAction secondaryApplyActionOverride { get; set; }
  Override accessor for secondary apply action.

• protected IProxyAction cancelActionOverride { get; set; }
  Override accessor for cancel action.

• private protected virtual IEnumerable<IProxyAction> toolActions { get; }
  Virtual enumerable that derived tools can yield to add their own IProxyActions (default empty).

• private IEnumerable<IProxyAction> baseToolActions { get; }
  Internal enumerable that yields the tool's default actions (default apply, secondary, cancel and mouse actions).

• internal IEnumerable<IProxyAction> actions { get; }
  Concatenation of baseToolActions and toolActions — the full set of actions for this tool instance.

• private protected bool actionsEnabled { get; private set; } = true
  Flag that controls whether actions are currently enabled (toggled by ToggleToolOptions).

• public static event Action<ProxyAction> EventToolActionPerformed
  Static event raised when any tool action is performed (InputActionPhase.Performed). Consumers can listen for tool action events.

Constructors

• protected ToolBaseSystem()
  Preserve-tagged default constructor. Registers the tool with the ToolSystem on creation; initializes action proxies (from InputManager), sets default requirements and default snap (Snap.All), disables the system by default and sets up an error query and infomode list. Derived tools should call base.OnCreate() when overriding OnCreate.

Methods

• public virtual void GetUIModes(List<ToolMode> modes)
  Hook for derived types to provide UI modes (tool modes shown in UI). Default implementation does nothing.

• public bool Equals(ToolBaseSystem other)
  IEquatable implementation; compares instance identity.

• protected override void OnCreate()
  Initializes references to world systems (ToolSystem, PrefabSystem, DefaultToolSystem, ToolRaycastSystem, OriginalDeletedSystem), fetches input actions for the tool type from InputManager, initializes default requirements, sets selectedSnap to Snap.All, disables the system by default and registers this tool with m_ToolSystem. Derived classes should call base.OnCreate().

• protected override void OnFocusChanged(bool hasfocus)
  Tracks focus changes and toggles m_FocusChanged accordingly.

• protected override void OnStartRunning()
  Called when the system starts running: forces an update and sets up actions (SetActions).

• protected override void OnStopRunning()
  Clears infoview/infomodes and resets actions. Calls base.OnStopRunning().

• private protected virtual void SetActions()
  Sets up actions by calling UpdateActions and enabling interaction via SetInteraction(true). Tools can override to customize.

• private protected virtual void ResetActions()
  Disables actions, clears any overrides, and re-enables actionsEnabled flag. Uses ProxyAction.DeferStateUpdating() to batch updates.

• private protected virtual void UpdateActions()
  Hook for derived classes to (re-)configure action enabled state and overrides. Default does nothing.

• private void SetInteraction(bool set)
  Wires or unwires OnActionInteraction to/from each ProxyAction associated with this tool. Collects unique ProxyAction instances from actions and base stateful UI actions.

• public void ToggleToolOptions(bool enabled)
  Toggles actionsEnabled (used to temporarily disable tool actions while options UI is open) and calls UpdateActions().

• private void OnActionInteraction(ProxyAction action, InputActionPhase phase)
  Internal callback for action interactions; if phase is Performed, raises EventToolActionPerformed.

• protected sealed override void OnUpdate()
  Sealed override that forwards to virtual OnUpdate(JobHandle) and clears focus/force-update flags after scheduling.

• protected virtual JobHandle OnUpdate(JobHandle inputDeps)
  Virtual update entry for derived systems; default returns inputDeps. Derived tools should implement their update logic and return the resulting JobHandle.

• public abstract PrefabBase GetPrefab()
  Derived classes must return the currently selected prefab (or null).

• public abstract bool TrySetPrefab(PrefabBase prefab)
  Attempt to set the tool's prefab. Returns true if accepted.

• public virtual void InitializeRaycast()
  Initializes m_ToolRaycastSystem defaults for a typical tool: clears many raycast flags, sets collision mask to OnGround|Overground, clears type/area/net masks, clears offsets etc. Tools should call or extend this to set custom raycast behavior.

• public virtual void GetAvailableSnapMask(out Snap onMask, out Snap offMask)
  Derived tools can populate available snap masks. Default sets both to Snap.None.

• public virtual void SetUnderground(bool underground)
  Hook to toggle underground placement mode. Default does nothing.

• public virtual void ElevationUp()
  Hook to increase elevation level. Default does nothing.

• public virtual void ElevationDown()
  Hook to decrease elevation level. Default does nothing.

• public virtual void ElevationScroll()
  Hook to respond to elevation scroll input. Default does nothing.

• public static Snap GetActualSnap(Snap selectedSnap, Snap onMask, Snap offMask)
  Static helper that computes the effective snap mask given selected, on and off masks: (selected | ~offMask) & onMask.

• protected Snap GetActualSnap()
  Instance helper using the tool's selectedSnap, m_SnapOnMask and m_SnapOffMask.

• protected void UpdateInfoview(Entity prefab)
  Populates infoview and infomodes based on the given prefab entity. If the prefab is a Net with subobjects marked MakeOwner the owner prefab is discovered and used; then PlaceableInfoviewItem buffer is read to populate the primary infoview (infoview) and additional infomodes (infomodes list).

• protected JobHandle DestroyDefinitions(EntityQuery group, ToolOutputBarrier barrier, JobHandle inputDeps)
  Schedules a parallel job (DestroyDefinitionsJob) that destroys entities in the given query (CreationDefinition entities not yet updated). Adds the scheduled job to the provided barrier for producer synchronization. Returns the scheduled JobHandle, or inputDeps if the group is empty.

• protected JobHandle InvertBrushes(EntityQuery group, JobHandle inputDeps)
  Schedules the InvertBrushesJob to negate brush strengths on Brush components in the given query. Useful when applying inverted brush effects. Returns scheduled JobHandle or inputDeps if the group is empty.

• protected virtual bool GetAllowApply()
  Checks whether the tool may apply changes: returns true if m_ToolSystem.ignoreErrors is set or there are no Error entities (m_ErrorQuery empty), and the OriginalDeletedSystem's original deleted result for stage 0 is false. Override to apply different rules.

• protected bool GetRaycastResult(out Entity entity, out RaycastHit hit)
  Queries m_ToolRaycastSystem for the current raycast result and ensures the owner is not marked Deleted. If a valid result is found returns true and outputs the owner entity and RaycastHit.

• protected bool GetRaycastResult(out Entity entity, out RaycastHit hit, out bool forceUpdate)
  Same as above but also returns whether a forced update is required (based on OriginalDeletedSystem or m_ForceUpdate).

• protected virtual bool GetRaycastResult(out ControlPoint controlPoint)
  If there is a valid raycast result returns a ControlPoint constructed from the owner entity and hit.

• protected virtual bool GetRaycastResult(out ControlPoint controlPoint, out bool forceUpdate)
  Version that also returns forceUpdate flag.

• protected bool GetContainers(EntityQuery group, out Entity laneContainer, out Entity transformContainer)
  Searches the given query's entity array for entities that have NetData (laneContainer) or ObjectData (transformContainer) and returns them. Returns false when the query is empty.

• protected BrushPrefab FindDefaultBrush(EntityQuery query)
  Iterates over entities in query to find the BrushPrefab with the lowest BrushData.m_Priority. Uses cached ComponentTypeHandles from __TypeHandle. Returns the found BrushPrefab or null.

• protected void EnsureCachedBrushData()
  Ensures that a brush prefab's BrushData contains a cached (possibly downsampled) resolution and fills the BrushCell buffer from the brush texture pixels scaled to the cached resolution. This prevents repeated expensive texture reads at runtime.

• protected EntityQuery GetDefinitionQuery()
  Convenience query: CreationDefinition (read-only) and excludes Updated. Used to fetch pending creation definitions.

• protected EntityQuery GetContainerQuery()
  Returns a query for EditorContainerData (containers used by editor tools).

• protected EntityQuery GetBrushQuery()
  Returns a query for BrushData (read-only).

• protected void SetAction(ref IProxyAction action, IProxyAction newAction)
  Replaces a stored IProxyAction while preserving the enabled state (disables old action and enables the new action with the old enabled state). Passing null will disable the action.

• private void __AssignQueries(ref SystemState state)
  Compiler helper stub used during generated OnCreateForCompiler. (Internal use; not for tools to call.)

• protected override void OnCreateForCompiler()
  Compiler helper that assigns query and type handles during build. Calls __AssignQueries and __TypeHandle.__AssignHandles. (Internal.)

• public virtual void GetUIModes(List<ToolMode> modes)
  (duplicate listed earlier) Hook to enumerate UI modes.

• protected virtual JobHandle OnUpdate(JobHandle inputDeps)
  (duplicate earlier) The main per-frame/task scheduling entry for derived tools.

• public virtual bool TrySetPrefab(PrefabBase prefab)
  (duplicate) Abstract; derived classes implement.

• public abstract PrefabBase GetPrefab()
  (duplicate) Abstract; derived classes implement.

• public override string ToString() (inherited)
  Use default; not overridden here.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate(); // registers tool, fetches default input actions, sets defaults

    // set default tool settings
    selectedSnap = Snap.All;
    allowUnderground = true;
    brushSize = 5.0f;
    brushStrength = 1.0f;

    // initialize raycast to a typical state for this tool
    InitializeRaycast();
}

// Example of overriding update to use raycast and apply logic (simplified)
protected override JobHandle OnUpdate(JobHandle inputDeps)
{
    // perform immediate (main-thread) logic, enqueue jobs as needed and return their handle
    if (GetRaycastResult(out Entity hitEntity, out RaycastHit hit))
    {
        // process hit, update tool visuals, etc.
    }
    return inputDeps;
}

---