Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/codewriter-packages/UniMob
Modern reactive programming library for Unity (inspired by MobX js)
https://github.com/codewriter-packages/UniMob
c-sharp design-pattern design-patterns game game-development game-engine gamedev paradigm paradigmshift reactive-programming state-management ui ui-framework ui-widgets unity unity3d widgets
Last synced: 3 months ago
JSON representation
Modern reactive programming library for Unity (inspired by MobX js)
- Host: GitHub
- URL: https://github.com/codewriter-packages/UniMob
- Owner: codewriter-packages
- License: mit
- Created: 2020-08-02T12:27:30.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-12-09T07:45:39.000Z (11 months ago)
- Last Synced: 2024-07-15T18:34:31.075Z (4 months ago)
- Topics: c-sharp, design-pattern, design-patterns, game, game-development, game-engine, gamedev, paradigm, paradigmshift, reactive-programming, state-management, ui, ui-framework, ui-widgets, unity, unity3d, widgets
- Language: C#
- Homepage:
- Size: 164 KB
- Stars: 181
- Watchers: 5
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# UniMob [](#) [](#)  [](https://openupm.com/packages/com.codewriter.unimob/)
UniMob is a library that makes state management simple and scalable by transparently applying functional reactive programming. The philosophy behind UniMob is very simple:
> _Anything that can be derived from the application state, should be derived. Automatically._
:small_blue_diamond: **Long lived.** More than five years of development and support
:small_blue_diamond: **Battle tested.** Used in games with millions of players
:small_blue_diamond: **Modern.** Based on the latest trends
:small_blue_diamond: **Open Source.** Can be used for free in any project
## :bulb: Influences
UniMob inspired by [MobX](https://github.com/mobxjs/mobx) and [$mol_atom](https://github.com/eigenmethod/mol/tree/master/atom) and adapts the principles of reactive programming for Unity.
## :thought_balloon: Motivation
Reactive programming is good for building application logic and user interface in particular. This approach is extremely popular on the web and currently spreading in native development ([Android](https://developer.android.com/jetpack/compose/state), [iOS](https://developer.apple.com/documentation/combine/observableobject)).
However, there is only one implementation of reactive programming for Unity: [UniRx](https://github.com/neuecc/UniRx). UniRx is a great solution when calculations are distributed over time (such as delays and network requests). However, for modeling business logic and user interface, the ability to dynamically combine multiple reactive streams is much more important. And here Rx becomes too complicated. Select, Merge, Combine and other operators are extremely difficult for complex scenarios.
UniMob takes a different approach to building reactive streams and aims to make combining reactive streams the same as writing regular code.
## :rocket: A quick example
So what does code that uses UniMob look like?
```csharp
using UniMob;
using UnityEngine.UI;
public class SampleCounter : LifetimeMonoBehaviour
{
public Text counterText;
public Button incrementButton;
// declare reactive property
[Atom] private int Counter { get; set; }
protected override void Start()
{
// increment Counter on button click
incrementButton.onClick.AddListener(() => Counter += 1);
// Update counterText when Counter changed until Lifetime terminated
Atom.Reaction(Lifetime, () => counterText.text = "Tap count: " + Counter);
}
}
```
## :receipt: Core concepts
UniMob has only a few core concepts.
### :label: Observable state
UniMob adds observable capabilities to existing data. This can simply be done by annotating your class properties with the `[Atom]` attribute.
```csharp
using UniMob;
public class Todo : ILifetimeScope
{
public Todo(Lifetime lifetime) { Lifetime = lifetime; }
public Lifetime Lifetime { get; }
[Atom] public string Title { get; set; } = "";
[Atom] public bool Finished { get; set; } = false;
}
```
Using `[Atom]` is like turning a property of an object into a spreadsheet cell that when modified may cause other cells to automatically recalculate or trigger reactions.
### :label: Computed values
With UniMob you can define values that will be derived automatically when relevant data is modified.
```csharp
using UniMob;
using System.Linq;
public class TodoList : ILifetimeScope
{
public TodoList(Lifetime lifetime) { Lifetime = lifetime; }
public Lifetime Lifetime { get; }
[Atom] public Todo[] Todos { get; set; } = new Todo[0];
[Atom] public int UnfinishedTodoCount => Todos.Count(todo => !todo.Finished);
}
```
UniMob will ensure that `UnfinishedTodoCount` is updated automatically when a todo is added or when one of the finished properties is modified. Computations like these resemble formulas in spreadsheet programs like MS Excel. They update automatically and only when required.
### :label:Reactions
Reactions are similar to a computed value, but instead of producing a new value, a reaction produces a side effect for things like printing to the console, making network requests, updating the UniMob.UI widgets, etc. In short, reactions bridge reactive and imperative programming.
#### UniMob.UI widgets
If you are using [UniMob.UI](https://github.com/codewriter-packages/UniMob.UI), you can use observable state in your widgets. UniMob will make sure the interface are always re-rendered whenever needed. (See [TodoList sample](https://github.com/codewriter-packages/UniMob.UI-Samples/tree/main/SimpleTodoList) for more info)
```csharp
public class TodoListApp : UniMobUIApp
{
private TodoList todoList = new TodoList();
protected override Widget Build(BuildContext context)
{
// Render scrollable list with todos,
// list will be automatically updated when todos changed
return new ScrollList {
Children = {
todoList.Todos.Select(todo => BuildTodo(todo))
}
};
}
private Widget BuildTodo(Todo todo)
{
return new TodoWidget(todo) { Key = Key.Of(todo) };
}
}
```
#### Custom reactions
Custom reactions can simply be created using the `Reaction` or `When` methods to fit your specific situations.
For example the following `Reaction` prints a log message each time the amount of `UnfinishedTodoCount` changes:
```csharp
Atom.Reaction(Lifetime, () => {
Debug.Log("Tasks left: " + todoList.UnfinishedTodoCount);
});
```
> [!IMPORTANT]
> Why does a new message get printed each time the UnfinishedTodoCount is changed? The answer is this rule of thumb:
> **_UniMob reacts to any existing observable property that is read during the execution of a tracked function._**
### :label: Lifetime
UniMob handles atom lifecycle with Lifetime concept. Each atom is scoped to it's LIfetime (App Lifetime, View Lifetime, etc.). When Lifetime become disposed all scoped atoms automatically deactivates too. This allow to get rid of manual lifetime management complexity (such as Subscription pattern).
### :label: Actions
UniMob is unopinionated about how user events should be handled.
- This can be done with Tasks.
- Or by processing events using UniRx.
- Or by simply handling events in the most straightforward way possible.
In the end it all boils down to: Somehow the state should be updated.
After updating the state UniMob will take care of the rest in an efficient, glitch-free manner. So simple statements, like below, are enough to automatically update the user interface.
```csharp
todoList.Todos = todoList.Todos
.Append(new Todo("Get Coffee"))
.Append(new Todo("Write simpler code"))
.ToArray();
todoList.Todos[0].Finished = true;
```
## :open_book: How to Install
Minimal Unity Version is 2019.3.
Library distributed as git package ([How to install package from git URL](https://docs.unity3d.com/Manual/upm-ui-giturl.html))
Git URL: `https://github.com/codewriter-packages/UniMob.git`
## :green_book: License
UniMob is [MIT licensed](./LICENSE.md).