Documentation: 0.5.0 (source: v0.5.0).
# Factions

> The three factions, standing, economics, diplomacy, and who owns what.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/factions/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Star Atlas has three factions — ONI, MUD, and Ustur — and a player belongs to
one. Faction is a capability-only entry, imported directly.

```ts
import {
  getFaction,
  maybeGetFactionStanding,
} from '@aephia/atlas-kit/factions';
```

:::game[MUD, ONI, and Ustur are the three player factions]
Choosing a faction places a player on one of the three major sides in the
galaxy. The factions are not simple character classes with permanent bonuses.
What separates them in play is the territory and assets they control, the
resources and money available to them, and their current relationships with
the other factions. In future gameplay, a player's standing is intended to
record how that individual is doing with a faction and change as the player
contributes or takes actions.
:::

## What this entry covers

It is broader than "which faction is this player in":

- **identity and configuration** — the faction itself
- **economics** — its economic state
- **diplomacy** — relations between factions
- **standing** — a profile's standing with a faction
- **treasuries and asset ownership** — what a faction holds
- **King-system ownership** — which faction controls which system

```ts
const faction = await getFaction(ctx, factionId);
const relations = await getFactionRelations(ctx);
const standing = await maybeGetFactionStanding(ctx, profileAddress, factionId);
```

> **Runnable example — Read a faction and a standing.** One faction by id, and a profile standing with it - which may not exist. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/factions/.

## `maybe` means it can be absent

`maybeGetFactionStanding` returns `undefined` rather than throwing when a
profile has no standing recorded. That is the SDK's convention throughout:
`get*` asserts existence, `maybe*` treats absence as a legitimate answer.

Use `maybe*` when absence is expected, and `get*` when it would be a bug.

## Gotchas

**Faction 0 is not a faction.** NPC-owned entities decode with `faction: 0`.
Their identity comes from the owning profile, not that field.

**Standing is per profile, not per character.** It belongs to the wider Star
Atlas identity rather than to the SAGE character.

**Relations are between factions, not players.** Diplomacy describes the
factions' stances toward each other.

## Reference

- [`factions`](/reference/factions/) — every export in this entry
- [`loyalty`](/guides/loyalty/) — contributing to a faction over an epoch
- [`identity`](/guides/identity/) — the profile standing attaches to