Dev: Understanding the `FiniteStateDevice` Class

If you've spent any decent amount of time trawling the underbelly of TXEnginePy's codebase, you've probably notice that essentially every class inherits from FiniteStateDevice, LoadableMixin, or (usually) both.

A class inheriting from 'FiniteStateDeviceis often accompanied by a large vomituous pile of calls to funky decorators such asFiniteStateDevice.state_logicandFiniteStateDevice.state_content`. What gives?

This page is dedicated to helping you understand not only what a FiniteStateDevice is, but how it works (and how you might make your own)!

What is a FiniteStateDevice?

The FiniteStateDevice class is a foundational block of TXEnginePy. It defines a consistent way of modeling the behavior of the user-interactable elements that power the engine.

To understand how a FiniteStateDevice works, we must first define its properties.

Note that theFiniteStateDevice class is modeled after the Finite State Machine computer-science concept.

A FiniteStateDevice, much like its name implies, is a logical construct that has a pre-defined, unchanging set of states. Each FiniteStateDevice's behavior is split into two halves: state logic, and state content. So, for any given state within the FiniteStateDevice, there must also be explicitly defined logic for that state and explicitly defined user-facing content for that state. For each state, the FiniteStateDevice must also define an expected user-input-type (int, bool, str, etc) and corresponding input limits (such as an int min or max) should any apply.

The game_state_controller (a global singleton instance of the GameStateController class) maintains an internal stack of FiniteStateDevices and queries the top-level device to retrieve the content to show the player. The top-level FiniteStateDevice then checks what state it is in, then retrieves the content defined for that state. When the user submits some input to the game, the game_state_controller delivers that input to the top-level FiniteStateDevice, which is then subsequently handed down to the current state's logic definition. The state executes its internally defined logic, and transitions to the next state.