# States

You may notice that our user commands receive an object called `state`
as part of the argument list.

## Transaction management

States are used for tracking the state of a current user command execution. For instance,
you will generally have to do a series of operations which, depending on the overall outcome
of your user command execution, should all be stored (or all discarded if a failure occurs).
States provide the mechanism for stacking operations which need to occur, and then commit
them in one shot.

## Transactional storage

> lib/modules/players/usercommands/registerManyBroken.js

```javascript
var mage = require('mage');

exports.acl = ['*'];

exports.execute = function (state, credentialsOne, credentialsTwo, callback) {
	mage.players.register(state, credentialsOne, function () {
  	mage.players.register(state, credentialsTwo, function () {
			var error = new Error('Whoops this failed!');
			return state.error(error, error, callback);
		});
	});
};
```

In the example here, we basically error out on purpose, but the purpose is clear:
we are trying to register two new users. However, because we end up calling `state.error`
the actions will not be executed; the two `mage.players.register` calls we have made
would only store information if the call succeded.

For more information about the API you use to access your data store, please read the
[Archivist](./api/classes/archivist.html) API documentation.

## Transactional event emission

> lib/modules/players/usercommands/registerAndNotifyFriend.js

```javascript
var mage = require('mage');

exports.acl = ['*'];

exports.execute = function (state, credentials, friendId, callback) {
	state.emit(friendId, 'friendJoined', credentials.username);

	mage.players.register(state, credentials, function (error) {
		if (error) {
			return state.error(error, error, callback);
		}

		callback();
	});
};
```

The state object is also responsible for emitting events for players. The event system is what
enables the MAGE server and MAGE clients to stay synchronized, and is also the first-class
communication interface to get players to send data between each others.

Events also benefit of the transactional nature of states; events to be sent to users
will not be sent unless the call succeeds. For instance, in this example, if `mage.players.register`
were to return an error, the event emitted by `state.emit` would never be sent to the other
player referenced by `playerId`.

For more information on the State API and how events are emitted, please read the
[State](./api/interfaces/mage.core.istate.html) API documentation.