MonoFSM Framework

Overview

MonoFSM is a comprehensive Finite State Machine (FSM) framework for Unity, designed to simplify the implementation of complex game behaviors and logic. The framework provides a visual and modular approach to designing state machines, making it easier to create, debug, and maintain game systems.

Nine Sols is the first project to use this framework, and it has been developed and tested in the context of that game.

Pre-requirement Dependencies

Paid Tools

• Odin-Inspector

Free Tools

• Unity Official Package
  • Unity.Addressable
  • Unity.Timeline
• ThirdParty Tools
  • UniTask
  • ZString
  • PrimeTween

Included in Project (with modification)

• Auto Attribute
• GuidManager
• System.Runtime.CompilerServices.Unsafe

Installation

Recommended

We recommend installing MonoFSM_Core_Utility first. It provides editor tools that can automatically install and configure the free/open-source dependencies for you.

⚠️ Note: Some plugins still require manual installation (see below).

Required Manual Installation

The following must always be installed manually regardless of whether you use MonoFSM_Core_Utility:

1. Install Odin Inspector (Paid)
   • Purchase and install Odin Inspector from the Asset Store

Auto-installable via MonoFSM_Core_Utility

The following dependencies can be installed automatically via the editor tools in MonoFSM_Core_Utility. You may also install them manually if preferred:

2. Install Unity Official Packages

   • Open Package Manager → Unity Registry
   • Install Addressables package
   • Install Timeline package

3. Install Third-Party Packages

   • UniTask: Add https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask via Package Manager
   • ZString: Add https://github.com/Cysharp/ZString.git?path=src/ZString/Assets/Scripts/ZString via Package Manager
   • PrimeTween: Add https://github.com/KyryloKuzyk/PrimeTween.git via Package Manager

Install MonoFSM

• Quick Setup: Install through Unity Package Manager with git url
• For Contributors: Use "git submodule" to include this module into your project, and add as local package through Unity Package Manager

Why Use MonoFSM?

1. Seamless Integration in Unity's Scene Hierarchy

   MonoFSM appears directly in Unity's Scene hierarchy, allowing roles like programmers, designers, and artists to work on the same objects naturally. This fosters organic information sharing within the project and reduces the need for extensive documentation.

2. Prefab-Based Extensibility and Reusability

   By leveraging Unity's Prefab and Prefab Variant system, MonoFSM overcomes the traditional FSM limitations of poor reusability and difficulty in expansion, making it straightforward to build and extend state machines.

3. Intent-Driven Dependency Injection (DI)

   Using GameObjects as the foundation allows for clear and intuitive dependency injection. Object activation and deactivation become explicit expressions of intent, which can be further interpreted and adapted later.

4. Tight Integration with Unity's Native Tools

   Because MonoFSM is built on GameObjects, it naturally supports Unity's Animation Clips and Timeline. This enables designers to create timeline-driven state machines with fine-grained, time-based control suitable for level design and gameplay micro-adjustments.

Core Features

Visual State Management

MonoFSM integrates directly into Unity's Scene hierarchy, making state machines visible and editable as GameObjects.

• GameObject-based States: States appear as GameObjects in the hierarchy, enabling intuitive drag-and-drop design
• Complete Lifecycle: Full support for OnStateEnter, OnStateUpdate, OnStateExit, and OnStateFinally methods
• Safe Transitions: Provides both safe and overwrite transition modes to prevent state conflicts

Variable System

Powerful variable management with cross-state data sharing and real-time monitoring capabilities.

• Typed Variables: Built-in support for VarBool, VarInt, VarFloat, VarString, VarTransform, and custom types
• Dynamic Binding: Variable binding system with change listeners for reactive programming
• Tag Organization: VariableTag system for efficient variable categorization and lookup

Action & Condition Framework

Flexible action execution system with conditional logic for complex gameplay behaviors.