Package com.marslib.util

Class MARSStateMachine<S extends Enum<S>>

java.lang.Object
com.marslib.util.MARSStateMachine<S>
Type Parameters:
S - The enum type representing the set of valid states.
public class MARSStateMachine<S extends Enum<S>> extends Object
A validated, enum-based Finite State Machine supporting guarded transitions, entry/exit actions, and transition callbacks.

This FSM enforces an explicit transition table: only pre-registered transitions are allowed. Illegal transition requests are logged and rejected, preventing undefined mechanism states that could cause collisions or damage. The FSM tracks ticks spent in each state for timeout-based logic.

Students: Use this class to coordinate multi-step mechanisms (e.g., intake → score sequences). Register allowed transitions with addValidTransition(S, S), then call requestTransition(S) to move between states safely.

  • Constructor Details

    • MARSStateMachine

      public MARSStateMachine(String name, Class<S> enumClass, S initialState)
      Constructs a new state machine.
      Parameters:
      name - Human-readable name for log output (e.g., "Superstructure").
      enumClass - The enum class token for the state type (e.g., MyState.class).
      initialState - The state the machine starts in.

  • Method Details

    • addTransition

      public void addTransition(S from, S to)
      Registers a one-directional transition from from to to.
      Parameters:
      from - The source state.
      to - The destination state.

    • addValidTransition

      public void addValidTransition(S from, S to)
      Alias for addTransition(Enum, Enum).
      Parameters:
      from - The source state.
      to - The destination state.

    • addValidBidirectional

      public void addValidBidirectional(S a, S b)
      Registers transitions in both directions between a and b.
      Parameters:
      a - The first state.
      b - The second state.

    • addWildcardTo

      public void addWildcardTo(S targetState)
      Makes targetState reachable from every state in the enum.
      Parameters:
      targetState - The state that all others can transition to.

    • addWildcardFrom

      public void addWildcardFrom(S fromState)
      Makes fromState able to transition to every state in the enum.
      Parameters:
      fromState - The state that can go anywhere.

    • isTransitionLegal

      public boolean isTransitionLegal(S nextState)
      Checks whether a transition from the current state to nextState would be accepted, without actually performing it.
      Parameters:
      nextState - The proposed destination state.
      Returns:
      true if the transition is legal (including self-transitions).

    • requestTransition

      public boolean requestTransition(S nextState)
      Attempts to transition from the current state to nextState. If the transition is legal, exit actions, the transition callback, and entry actions fire in sequence and the state changes. Self-transitions are always accepted but do NOT fire any actions. Illegal transitions are logged and rejected.
      Parameters:
      nextState - The desired state.
      Returns:
      true if the transition was accepted, false if rejected.

    • getState

      public S getState()
      Returns the current active state.
      Returns:
      The current state enum value.

    • getTicksInCurrentState

      public int getTicksInCurrentState()
      Returns the number of ticks since the last transition.
      Returns:
      Tick count in the current state (incremented by update()).

    • getPreviousState

      public S getPreviousState()
      Returns the state that was active before the most recent transition.
      Returns:
      The previous state enum value.

    • getTotalTransitionCount

      public int getTotalTransitionCount()
      Returns the total number of accepted (non-self) transitions since construction.
      Returns:
      Cumulative transition count.

    • setEntryAction

      public void setEntryAction(S state, Runnable action)
      Registers a callback to run when entering the specified state.
      Parameters:
      state - The state whose entry triggers the action.
      action - The callback to execute on entry.

    • setExitAction

      public void setExitAction(S state, Runnable action)
      Registers a callback to run when exiting the specified state.
      Parameters:
      state - The state whose exit triggers the action.
      action - The callback to execute on exit.

    • setOnTransition

      public void setOnTransition(BiConsumer<S,S> callback)
      Registers a callback that fires on every accepted transition, receiving the source and destination states.
      Parameters:
      callback - A BiConsumer that receives (fromState, toState).

    • update

      public void update()
      Increments the tick counter for the current state. Must be called once per subsystem periodic loop — if omitted, getTicksInCurrentState() will not advance and timeout-based logic will break.

    • generateMermaidGraph

      public String generateMermaidGraph()
      Generates a Mermaid.js State Diagram representing all valid transitions and states. This logic dynamically tracks the active node, creating a live flowchart visualization of the Subsystem that can be viewed natively in AdvantageScope.
      Returns:
      A string formatted as a valid Mermaid stateDiagram-v2 markdown block.