more documentation (1643ea26) · Commits · thatcosmonaut / stately

docs/index.rst

+1 −2

Original line number	Diff line number	Diff line
		@@ -16,8 +16,7 @@ Read on...
		Quickstart Guide <quickstart>
		State <state>
		Transition <transition>
		Timer <timer>
		license
		License <license>

		Get Stately
		-----------

docs/license.rst

+3 −4

Original line number	Diff line number	Diff line
		License
		=======


		GNU LESSER GENERAL PUBLIC LICENSE
		Version 3, 29 June 2007

		@@ -823,11 +822,11 @@ If the program does terminal interaction, make it output a short
		notice like this when it starts in an interactive mode:

		stately Copyright (C) 2018 Evan Hemsley
		This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
		This program comes with ABSOLUTELY NO WARRANTY; for details type ``show w``.
		This is free software, and you are welcome to redistribute it
		under certain conditions; type `show c' for details.
		under certain conditions; type ``show c`` for details.

		The hypothetical commands `show w' and `show c' should show the appropriate
		The hypothetical commands ``show w`` and ``show c`` should show the appropriate
		parts of the General Public License. Of course, your program's commands
		might be different; for a GUI interface, you would use an "about box".

docs/quickstart.rst

+71 −9

Original line number	Diff line number	Diff line
		@@ -63,11 +63,13 @@ ground and presses the jump button. A simple task, with the power of state machi

		idleState.ChangeTo(jumpState).If(() => Input.GetButtonDown("Jump"));

		jumpState.OnEnter = delegate {
		jumpState.OnEnter = delegate
		{
		velocity = new Vector3(0f, 5f, 0f);
		};

		jumpState.OnUpdate = (deltaTime) => {
		jumpState.OnUpdate = (deltaTime) =>
		{
		velocity.y -= 0.5f * deltaTime;
		};

		@@ -82,8 +84,8 @@ ground and presses the jump button. A simple task, with the power of state machi

		Let's break down what's going on here.

		Defining State Behavior
		-----------------------
		State Behavior
		--------------

		.. code-block:: csharp

		@@ -95,7 +97,8 @@ of the object.

		.. code-block:: csharp

		jumpState.OnEnter = delegate {
		jumpState.OnEnter = delegate
		{
		velocity = new Vector3(0f, 5f, 0f);
		};

		@@ -105,7 +108,8 @@ to ``{0f, 5f, 0f}``.

		.. code-block:: csharp

		jumpState.OnUpdate = (deltaTime) => {
		jumpState.OnUpdate = (deltaTime) =>
		{
		velocity.y -= 0.5f * deltaTime;
		};

		@@ -115,8 +119,10 @@ In this case, to simulate the effects of gravity, we want to
		decrease the object's ``y`` velocity by a factor of half the time step on each
		update tick.

		Defining Transitions
		--------------------
		For more information on defining State behavior, check the :ref:`State documentation <state>`.

		Transitions
		-----------

		.. code-block:: csharp

		@@ -155,7 +161,8 @@ this with a transition callback.
		{
		// ...

		idleState.ChangeTo(jumpState).If(() => Input.GetButtonDown("Jump")).ThenDo(() => {
		idleState.ChangeTo(jumpState).If(() => Input.GetButtonDown("Jump")).ThenDo(() =>
		{
		dustParticleSystem.Emit(100);
		});

		@@ -164,3 +171,58 @@ this with a transition callback.

		`ThenDo` is used to specify a method which should be called when the transition is
		executed. It is executed after `OnExit` of the previous state and before `OnEnter` of the new state.

		Why would you use `ThenDo` instead of `OnExit`? Simply, if you have one state that
		branches into two other states, you can define transition-specific behavior
		depending on which transition is executed.

		For more information on defining Transitions, check the :ref:`Transition documentation <transition>`.

		Inheritance
		-----------

		The designer wants a new type of Cube that has slightly different behavior.
		This cube should emit lots more dust when it jumps. No problem!
		Stately has functions to redefine state behavior so you can avoid
		duplicating code.

		.. code-block:: csharp

		public class DustyCube : Cube
		{
		override void DefineStateMachine()
		{
		base.DefineStateMachine();

		idleState.OnTransitionTo(jumpState).InsteadDo(() =>
		{
		dustParticleSystem.Emit(1000);
		});
		}
		}

		Now 10 times more dust particles will be emitted by the cube when it jumps!
		Wow!

		The designer wants a different kind of cube now. This one should automatically
		jump two seconds after it touches the ground.

		.. code-block:: csharp

		public class AutoJumpCube : Cube
		{
		override void DefineStateMachine()
		{
		base.DefineStateMachine();

		idleState.ReplaceTransitionCondition(jumpState).With.After(2f);
		}
		}

		Now the cube will jump two seconds after entering the idle state! Easy!

		This concludes the quickstart guide. You should have a good overview of the concepts
		you'll need to build state machines with Stately.

		Please reference the class-specific documentation if you are
		in need of further clarification. I hope you enjoy building software with Stately!

docs/state.rst

+34 −61

Original line number	Diff line number	Diff line
		.. _state:

		State
		=====
		Note: all examples will assume that you have placed the following at the top
		of your code.

		::

		using Stately;

		A Stately state machine consists of a top-level state (known as the "root") and
		various substates which are defined using Transitions. You will only ever
		reference States directly.

		::

		State rootState = new State("root");
		various substates which are defined using Transitions. You will never reference
		Transition except through methods provided by State.

		A State consists of a name, various conditions for transitions between states,
		and callback functions to execute when states are entered, updated, or exited.

		The following is a basic example of a complete Stately state machine.

		.. code-block:: csharp

		State rootState = new State("root");

		State idleState = new State("idle");
		State jumpingState = new State("jumping");

		idleState.OnEnter = delegate {
		SetColor(Color.blue);
		};

		idleState.ChangeTo(jumpingState).After(2f);

		jumpingState.OnEnter = delegate {
		rigidbody.AddForce(300f * Vector3.Up);
		SetColor(Color.red);
		};

		jumpingState.ChangeTo(idleState).IfSignalCaught("touchedGround");

		rootState.StartAt(idleState);
		rootState.Start();

		Don't worry if you don't understand what this all means yet. We'll go through
		each type of transition and condition to help you construct your own state
		machines;

		Methods
		-------

		@@ -61,14 +24,9 @@ Methods
		* :func:`Transition OnTransitionTo(State otherState) <State.OnTransitionTo>`
		* :func:`Transition ReplaceTransitionCondition(State otherState) <State.ReplaceTransitionCondition`


		Callback Reference
		------------------
		``OnEnter``
		Runs as soon as the state is entered.

		Method Reference
		------------------

		.. function:: void Start()

		The final step in initializing the state machine. Should be called once and only
		@@ -99,11 +57,11 @@ to be used. Should only be called on the root state.

		.. function:: Transition ChangeTo(State otherState)

		:param State otherState: The state to create a ``Transition`` to.
		:returns: The ``Transition`` object between the two states.
		:param State otherState: The state to create a `Transition` to.
		:returns: The `Transition` object between the two states.

		The bread and butter of Stately. Creates a ``Transition`` object from the calling
		state to the given state. ``Transition`` objects are never created or
		The bread and butter of Stately. Creates a `Transition` object from the calling
		state to the given state. `Transition` objects are never created or
		manipulated directly. Instead, use expressions on states
		to define transition conditions and callbacks.

		@@ -129,11 +87,11 @@ to <transition>

		.. function:: AnyStateTransition ChangeToSubState(State otherState)

		:param State otherState: The state to create an ``AnyStateTransition`` to.
		:returns: The ``AnyStateTransition`` to the substate.
		:param State otherState: The state to create an `AnyStateTransition` to.
		:returns: The `AnyStateTransition` to the substate.

		Called from a higher-level state using a substate as a parameter. When the
		condition is met, it will transition from any substate into the given ``otherState``.
		condition is met, it will transition from any substate into the given `otherState`.
		Useful when you have many substates that can change between each other.

		States will not self-transition with this method.
		@@ -156,7 +114,7 @@ States will not self-transition with this method.

		rootState.StartAt(redState);

		Now, ``redState``, ``blueState``, ``greenState``, and ``yellowState`` can all
		Now, `redState`, `blueState`, `greenState`, and `yellowState` can all
		transition between each other,
		but we've narrowed this down to 4 transitions instead of 12. Nice!

		@@ -164,16 +122,16 @@ but we've narrowed this down to 4 transitions instead of 12. Nice!

		:param string signal: The signal to send to the state.

		For use with the ``IfSignalCaught`` transition condition.
		For use with the `IfSignalCaught` transition condition.
		This signal propagates recursively until a state with no substate is reached.

		.. function:: Transition OnTransitionTo(State otherState)

		:param State otherState: The other state.
		:returns: The already existing ``Transition`` object between these two states.
		:returns: The already existing `Transition` object between these two states.

		Used to redefine transition callbacks in conjunction with the ``InsteadDo`` and
		``AlsoDo`` methods. Useful for extending or modifying transition
		Used to redefine transition callbacks in conjunction with the `InsteadDo` and
		`AlsoDo` methods. Useful for extending or modifying transition
		behavior when inheriting classes that implement a state machine.

		Example
		@@ -189,9 +147,9 @@ Jumping now emits 500 dust particles instead of 100!
		.. function:: Transition ReplaceTransitionCondition(State otherState)

		:param State otherState: The other state.
		:returns: The already existing ``Transition`` object between these two states.
		:returns: The already existing `Transition` object between these two states.

		This function is similar to ``OnTransitionTo``, except that it erases the
		This function is similar to `OnTransitionTo`, except that it erases the
		transition condition so it can be replaced. Useful for extending or modifying
		transition behavior when inheriting classes that implement a state machine.

		@@ -204,6 +162,21 @@ transition behavior when inheriting classes that implement a state machine.
		Now the idle state will transition to the jumping state after 2 seconds instead
		of waiting for a button press.

		Callback Reference
		------------------

		``OnEnter``
		Runs when the state is entered.

		``OnUpdate``
		Runs on each update tick.

		``OnFixedUpdate``
		Runs on each FixedUpdate tick (convenience method for Unity).

		``OnExit``
		Runs when the state is exited.

		Property Reference
		------------------

docs/timer.rst

deleted100644 → 0

+0 −2

Original line number	Diff line number	Diff line
		Stately.Timer
		=============