📖 Darkstar Alliance Bot — Guide

Welcome! This guide walks through everything the bot can do for you. Most
commands are Discord slash commands — start typing / and Discord will
autocomplete them. A few older ones still use the ! prefix; both are shown
below where it matters.

New here? Start with Getting started.

Getting started

Before anything else, connect your Discord account to your Politics & War nation:

  • /register <nation_id> — verifies your nation and links it. This unlocks
    member commands and shows your current warchest readiness. You only do this once.

If your nation isn't in the alliance, or it's already linked to another account,
registration will tell you why.

Read alliance documents

The document library holds the alliance's guides, doctrines, and internal
references. Access is tied to your Discord identity.

  • /docs <document> — start typing a title, code, or category and Discord
    will autocomplete the documents you're allowed to see. The bot DMs you a
    permanent link like /d/YOUR-DOC-CODE. You can bookmark it and come back
    later; it stays yours.
  • /doc <id_or_code> — same idea if you already know the exact code.
  • Website — sign in at the dashboard and open Documents to browse the
    full library grouped by category.

House rules — read this once, it matters

Alliance documents are internal. Treat them like any classified material:

  • Do not share the link. Your link is bound to you. If someone else opens
    it, we know it came from your account.
  • Do not screenshot, copy-paste, print, or re-host the content. Every open
    page is uniquely traceable back to the viewer, including screenshots.
  • Do not paste document text into external tools, LLMs, or public channels.
  • Do not attempt to bypass, tamper with, or reverse-engineer the reader.
    This includes disabling scripts, modifying the page, or automating access.

Leaked content — in any form — will be traced. Enforcement is at the alliance's
discretion and can include loss of access, removal, and public disclosure of
the source. If in doubt about what you can quote or forward, ask an admin
first.

Reach the website

Signing in on the website with Discord gives you member/government pages
automatically. If someone needs access without the usual roles, an admin can
grant it manually — see Server setup & administration.

War & military

Find counters

  • /counter <nation_id_or_link> — generates a ranked counter list against a
    target, with paginated results and quick actions.
  • !war reliability [@member] — how reliable you (or a member) have been at
    following through on assigned counters.
  • !war war_status — which alliances/channels are being monitored.

Cost a war

  • /warcost <war_id_or_url> — full cost breakdown of a war: unit losses,
    infrastructure damage, resource consumption, loot, and net cost at market
    prices. Add -d for a per-resource breakdown.
  • /warcostranking timestart:7d coalition1:<nation or aa:id> — leaderboard of
    war damage/value over a time window, with rich filters (by stat, war type,
    per-city scaling, grouping, and more).

Keep enemies in beige

The beige-cycle system coordinates a group to keep an enemy nation in beige
indefinitely — when their war ends, a designated "finisher" is alerted to
re-declare before they can rebuild.

  • /cycle status [nation_id] — the active cycle for a target, or a summary of all.
  • /cycle list [status] — cycles filtered by status (default: active ones).
  • /cycle dm <on|off> — turn your cycle notification DMs on or off.

Officers (military) also have /cycle abort, /cycle reassign, and /cycle resume.

Beige sniping

Get alerted when watched nations leave beige and become attackable:

  • /beige_subscribe / /beige_unsubscribe — opt in or out of personal
    beige-snipe DMs.

Officers manage the watchlist and alerts channel with !beigesnipe alliance,
add, remove, sheet, list, status, setchannel, activate, and deactivate.

Blitz coordination (MilCom)

The !blitz toolset plans and dispatches coordinated attacks via a Google Sheet:

  • !blitz generate <attackers> <defenders> --sheet <url> — score targets and
    allocate attackers into the sheet (many tuning flags available).
  • !blitz validate, !blitz prep, !blitz send, !blitz status —
    validate the plan, run the readiness poll, dispatch orders, and track progress.

Spy operations & simulation

  • /spyranking channels:<#report-channels> — builds a saboteur leaderboard
    from your spy-report channels, reading both text and (optionally) screenshots.
  • !sim / !profile — AI battle simulation in a channel (restricted).

Your economy & warchest

Check income & raid targets

  • /revenue <nation_id or aa:alliance_id> — estimated net daily revenue for a
    nation or a whole alliance, broken down by city income, upkeep, and trade.
    Alliance results also include a true revenue line that excludes members
    inactive for 5+ days, so the total reflects income that will actually land.
  • /raids [score] — finds profitable raid targets in your war range.

Value a treasure

  • /treasurevalue — prices a treasure for a prospective holder, using the
    same income model as /revenue. With no options it values one more treasure
    for this server's alliance; the reply breaks down the marginal alliance bonus
    (it shrinks as an alliance stacks treasures), the eligible income base
    (applicants and off-color members excluded), daily and total value over the
    days left in the cycle, and a price per remaining day for negotiations.

Options: alliance (value it for a prospective buyer — their marginal
value is your asking ceiling), nation (a single holder nation: its 5% or
9% bonus plus the marginal bonus of its own alliance), treasure (standard
5% vs Hoa Hakananai'a / Holy Grail at 9%), days_remaining (override the
respawn timer), growth_percent (expected income growth by cycle end, for
valuations during a rebuild).

Plan your city build

  • /optimalbuild — computes the city build with the highest net daily revenue
    at current market prices, accounting for your continent's resources, your
    projects, and your policies. With no options it plans for your
    highest-infrastructure city. The reply includes a template you can copy
    straight into the game (city page → Import).

Everything it assumes can be overridden:

  • infra / land — plan for different city stats.
  • mmr — military slots, e.g. 0250 or 0/2/5/0
    (barracks/factory/hangar/drydock). By default the build reserves your
    alliance's MMR doctrine for your city count — it never suggests an army-less
    city unless you explicitly pass 0/0/0/0.
  • projects / no_projects — simulate owning (or not owning) projects,
    e.g. projects: itc,telecom,irrigation to see a build's worth after buying them.
  • policy and cities — assume a different domestic policy or city count.
  • continent — simulate another continent's mines (yours can't change in-game).

The reply lists the assumptions it used, so you always know what the numbers mean.

  • /buildpotential [alliance] — projects an entire alliance's revenue if every
    counted nation ran its optimal build in every city. Two figures come back:
    the maximum theoretical (all members active in the last 5 days) and the
    realistic theoretical (also on the alliance's color or beige, MMR at least
    0030). Each filter reports how many nations it excluded, so you can see where
    the gap comes from. Both figures are net city revenue at market prices —
    military upkeep and the color bloc bonus are not included. Defaults to this
    server's alliance; pass an alliance name or id to evaluate another one.

Top up your warchest

  • /warchest_request [percentage] — generates a ready-to-copy request command,
    sized to bring your stockpile up to the chosen percentage of your alliance's
    warchest requirements. Paste the generated line into the grant bot. Works for
    members of the alliance and of its linked extensions.

Government sets those requirements with /set_warchest_requirement <resource> <amount> [alliance_id] — a per-city target for each resource. Leave
alliance_id empty for this server's alliance, or pass a linked extension's id
to configure that extension.

Alliance economics (Admin)

  • /economy status / /economy cache / /economy age — the alliance
    economic-data cache.
  • /economy simulate, /economy treatymap, /economy protect,
    and the chart views (/economy bar, scatter, treemap, pack).

Random inactivity purge (gov, opt-in)

  • /inactivitypurge on [max_per_day] / /inactivitypurge off /
    /inactivitypurge status — daily automated purge of the alliance's
    MEMBER nations that haven't logged in for at least 7 days and aren't in
    vacation mode. When on, the bot picks up to max_per_day (default 1) at
    random per UTC day and demotes them to Applicant. Demotions fire at a
    jittered UTC hour (12:00 ± 3h, derived per day so members can't predict
    it). A per-attempt re-check right before the mutation drops picks who
    logged back in since the scan. Persistent state means bot restarts can't
    double-demote in the same day.

The targeted member receives DMs at three stages: a heads-up at day 5, an
eligibility notice at day 7, and the demotion notice. Warnings only repeat
when the member was active in between (fresh streak).

Requires: a P&W bot key configured for this guild (super-admin only) and
an API key from a nation with change_permissions on the alliance.

Alliance militarisation snapshot

  • /militarization — lists every alliance nation (primary + linked
    extensions) ranked by militarisation percentage (soldiers/tanks/aircraft/
    ships normalised to per-city maxima, averaged) with the org-wide average
    at the top. VM / beige / 3d+ inactive nations are tagged inline with
    their timers. Truncates cleanly under Discord's 2000-char message cap.
  • Attached Filter button opens a modal that takes a comparator
    (>, <, >=, <=, =) and a percentage, then replies ephemerally
    with the matching nations (useful for "who is below 40%?").

Salaries (gov payroll)

  • /calc_salaries — computes government salaries plus MMR bonuses and outputs
    the transfer commands. Supporting commands: !salary gov_roles,
    !salary gov_linking, !salary test_mmr, !salary set_channel.

Alliance monitoring

The bot audits member stockpiles, warchests, and city builds every day at
14:00 UTC, posting reports to a staff channel. Nothing is posted until that
channel is set:

  • /set_audit_channel [#channel] (admin) — chooses where the daily audits post
    (omit the channel to turn them off). Optionally scope to warchest or stockpile.

You can also run an audit on demand — each audits this server's alliance:

  • /monitor stockpile_check — resource stockpile check.
  • /monitor warchest_audit (admin) — warchest readiness (uses the alliance
    requirements above).
  • /monitor build_audit (admin) — city build issues, with a link to the full
    sortable report on the website.

Channel & diplomatic audits (admin)

  • !audit channels — validates member ticket channels against nation links,
    sorts them into the right score-range category, and locks each ticket down to
    government roles + the ticket owner (fixing any wrong permissions). If it
    can't identify a ticket's owner, it leaves that channel untouched and says so.
  • !audit fa <category_ids> — AI-analyses foreign-affairs channels and files
    a diplomatic note per alliance.

Membership & community

Applicant pipeline

  • /ia status [@member] — an applicant's record, or the list of active applicants.

Government tracks and advances applicants with /ia stats, /ia audit,
/ia activity_overview, /ia colorcheck_overview, /ia academy, /ia escalate,
/ia flag, and /ia note. Admins have /ia setup, /ia override, /ia reset,
and /ia purge.

  • /ia sortapplicants — lists in-game applicants who are not on this Discord
    server, not in vacation mode, and inactive on P&W for 14+ days, then offers a
    confirmation button to remove all of them at once via
    assignAlliancePosition(REMOVE) (bot key required). Each removed applicant
    who linked their Discord receives a short DM inviting them to reapply — set
    the invite via !ia setting applicant_reapply_url <url> (falls back to the
    guild's vanity URL). Ex-members demoted to applicant for inactivity are
    spared because they remain on the Discord server. Every removal is logged in
    applicant_removal_log.

Engagement & discipline

  • /standing — check your own engagement standing: score breakdown, tier,
    tax rate, and active strikes. Government can check anyone with
    /standing @member.

Government commands:

  • !engagement standing [@member] / !engagement top — a member's standing
    or the leaderboard.
  • !engagement strike, !engagement clearstrike, !engagement strikes —
    issue, clear, and review disciplinary strikes.
  • !engagement order / !engagement orders — issue and track engagement orders.

Alliance MMR doctrine (government)

The MMR doctrine defines the required military slots per city range. It powers
the /optimalbuild default and the engagement standing penalties:

  • /mmr show — current doctrine per city range.
  • /mmr set <city_min> <city_max> <mmr> [infra_cap] — set a range, e.g.
    /mmr set 10 19 0250. Overlapping ranges are rejected with the conflict listed.
  • /mmr remove <city_min> <city_max> — delete a range.

Community activity

  • /count [what] [target] [duration] — count pings, messages, or users over a
    time window, optionally for one member.
  • !stats channels, !stats activity_heatmap, !stats member_decay,
    !stats contributor_distribution, and more — analytics on where and how the
    server is active (government/internal; run !stats backfill once first).
  • /honorific-check — lists long-serving members (1+ year) still at a low
    alliance position who may deserve the honorific role.

Reach members

  • /quick_dm @Role <message> — DM everyone in a role immediately.
  • !mass_dm — a guided flow (role picker, compose, confirm) for larger campaigns.
  • !dm_history — recent campaign results.

Intelligence & knowledge

Intelligence reports (government)

  • !intel analysis <channel_id> [notes] — builds an AI intelligence report from
    a join-ticket channel and delivers it in-channel, by DM, or to the archive.
  • !intel stats — usage and cost stats.

Oracle — the document assistant

Oracle answers questions about alliance documents and listens in configured
channels; just ask a question there.

  • !oracle tokens — your current session's usage.
  • !oracle clear — reset your conversation.
  • !oracle channels — where Oracle is active.

Forum news (internal)

  • !news setchannel [#channel] — where new P&W forum articles auto-post.
  • !news check — poll the forums now.
  • !news status — configuration and monitored feeds.

Awards & certifications

Ribbons are recognitions; diplomas are certifications — earned by passing a
formation on the website (or granted manually), some of them required before
joining government. Both have public web pages.

Certifications (diplomas)

  • /certifications [@member] — a member's certifications, plus a checklist
    of the ones required for government (what's earned, what's missing). Anyone
    can check anyone; certifications are public.
  • Earning a certification sends the member a congratulation DM and can grant a
    Discord role automatically.
  • Certifications are earned by completing a linked formation on the website
    with a sufficient score — see Membership & community.

There is no manual diploma creation: every certification is created
automatically when its formation is imported, from one unified certificate
template — the formation's name on an academic layout, with a QR code linking
to the certification's verification page. One formation, one certification,
always in sync.

Managing them (server Administrator):

  • !diploma set_requirement <id> <true|false> — mark it as required before
    joining government.
  • !diploma set_role <id> [@role] — the Discord role granted when earned
    (omit the role to clear).
  • !diploma set_visibility <id> <members|public> — public certifications
    have a web page (and QR code) viewable by anyone, even outside the alliance.
  • !diploma send <id> @user … / !diploma revoke <id> @user — grant or
    revoke manually.
  • !diploma regenerate <id> — re-render the certificate image.
  • !diploma list / !diploma info <id> / !diploma delete <id>.

Formation tests: import & export (government)

Every formation (its lessons, questions, correct answers, and certification
link) lives in one readable YAML file, so tests can be written, audited, and
edited outside the system — or generated from an existing form:

  • /formation export <module_id> — download a formation as a YAML file.
  • /formation import — attach an edited YAML file: it creates the
    formation (and its certification, automatically), or fully replaces it if the
    id already exists (submissions are kept). Every problem in the file is
    reported at once.
  • /formation set_visibility <module_id> <members|public> — public
    formations can be viewed and taken by any logged-in Discord user, not just
    alliance members.
  • /formation list — all formations with status and visibility.

The file starts with format: darkstar-formation/v1; export an existing
formation to get a template.

Ribbons

Recognitions under !ribbon (create, register, send, import, list,
info, delete) — same workflow as diplomas, lighter format.

Public pages live at …/diplomas/<id> and …/ribbons/<id> on the website.

Server setup & administration

First-time setup (super admin)

  • !reg set_guild_alliance <alliance_id> — bind this server to one alliance.
    Almost everything depends on this.
  • !reg link — bulk-match alliance nations to Discord members.

Extension alliances (super admin)

If your organization runs more than one in-game alliance, link the others as
extensions so the daily audits and war alerts cover them too:

  • /link_extension — opens a secure box to paste an API key belonging to the
    extension alliance. The bot verifies the key's owner is an officer, heir, or
    leader     there (proof you control it) and stores the key so it can read that
    alliance's data. You cannot link an alliance you don't hold a leadership key for.
  • /unlink_extension <alliance_id> — stop covering an extension.
  • /extensions — list the currently linked extensions.

Because P&W API keys only read their own alliance, each extension needs its own
key — that's why linking requires one.

Delegation (Discord admin)

If several Discord servers should share one alliance's setup (same alliance
binding, same API keys, same shared config), designate one as the main and
the others as delegates. Local things — permission-role mappings, channel
mappings, applicant workflow, engagement — stay per-server; a fresh delegate
starts blank so its admins configure their own roles and channels.

Both sides consent. On the main server:

  • /delegate propose <delegate_guild_id> — invite another server to become
    a delegate of this one.
  • /delegate revoke <delegate_guild_id> — end an active delegation.

On the delegate server:

  • /delegate accept <main_guild_id> — accept a pending proposal.
  • /delegate leave — leave the delegation.

/delegate list shows the current state on either side. Gating is Discord's
Administrator permission on both sides. If a server is itself a delegate it
can't also be a main — one alliance, one main.

Permission roles

Permissions are grouped into categories (government, military, internal,
economy, member, leader, and more) mapped onto your Discord roles:

  • /map_role @Role <category> — map a Discord role to a permission category
    for this server.
  • !role list_guild_roles / !role show @member — review mappings and a
    member's effective permissions.

Channel mapping (admin/internal)

  • /chanmap set <name> #channel — tell the bot which real channel a logical
    name refers to. Also /chanmap list, /chanmap unmapped, /chanmap remove.

Website access (super admin)

  • /set_website_access @user <government|member|revoke> — grant or revoke
    website access directly, independent of Discord roles or alliance membership.

API keys

Anyone can contribute their own P&W API key — more keys means faster, more
reliable data for your alliance:

  • /apikey add — opens a secure box to paste your key (it never appears in
    chat). The bot ties it to you and your alliance so it picks the most relevant
    key for each task.
  • /apikey list — shows your keys and their status.
  • /apikey remove <id> — removes one of your keys. You can only remove your
    own.

DM console (admin)

The website's DM console (/dms) shows every conversation the bot has had in
direct messages — both what members wrote and what the bot sent — like a
Discord DM list, with the ability to reply from the page.

  • !admin sync_dms — imports the bot's full DM history retroactively
    (checks every known member's conversation). Run it once to backfill the
    console; new messages are logged automatically as they happen.

Misc (restricted)

  • !admin flags refresh — refresh cached alliance flags.
  • !admin set_war_alerts_channel [#channel] — set the war-alerts channel.

What the bot does on its own

Beyond commands, the bot runs several things automatically:

  • Daily audits of stockpiles, warchests, and city builds (14:00 UTC).
  • Real-time war alerts — it listens to P&W's war feed and posts counter and
    war-cost reports as wars start and end.
  • Beige monitoring — alerts when watched nations leave beige, and drives the
    beige-cycle finisher DMs.
  • Applicant audits every 12 hours, including color-alignment checks.
  • Forum news — periodically posts summarised P&W forum articles.
  • Bi-weekly salary calculation for payroll.
  • Oracle answers document questions in its channels.

If something you expected didn't happen, it's usually because the server isn't
bound to an alliance yet, or a target channel hasn't been configured.