Agave Tequilana - Player Documentation
======================================
Agave Tequilana is an add-on for VGA Planets, modeled after the
Tequila War / Cactus add-on.
It implements a scoring system based on keeping and defending planets.
Scenario
--------
The non-profit Cactus Lovers Association iN Galaxy (CLANG) considers
its purpose the popularisation and cultivation of cactuses throughout
the galaxy. (Heretics claim that this religious organisation is just a
cover-up for the mighty, corrupt Galactic Cactus Corporation (GCC),
but that will be none of our business for now.)
CLANG missionaries roam the galaxy, and provide everyone who desires
with seedlings for Agave Tequilana, the, erm, cactus that provides us
with the noble spirit that is Tequila. All they ask in return is a
fair share of the Tequila produced. The canon says that the government
who produces the most Tequila under their reign will be the first to
rule the galaxy.
Now, all the people in the galaxy produce and collect Tequila. It
turns out, however, that invading neighbours' planets and plundering
their Tequila stockpile is a more efficient way to acquire juice.
CLANG on the other hand looks away from the fights... Tequila doesn't
smell, CLANG is happy when they receive their share, no matter from
whom.
In more mundane terms: declare planets important by planting cactuses
to produce score. Defend these planets because losing them gives you a
penalty, conquering them gives a bonus.
Cactus Rules
------------
This add-on keeps a score. The cactuses you own contribute to this
score each turn.
### Building
You can build cactuses on planets you own. To do so, send a message
cactus: build NNN
to yourself, where NNN is the planet Id. There may be requirements for
the planet (`ClansRequired`, `NeedBase`, `RebuildCactus`), and there
may be an overall limit for the number of cactuses you can build
(`CactusLimit`), but other than that you can build as many as you
want, whenever you want.
Building a cactus may cost score points (`CostAdditive` etc.).
Building cactuses may cause the score to go negative.
As long as you own the cactus, it will produce `TurnScore` points per
turn.
Instead of `build`, you can also write `defhw`.
### Capturing
Capturing a planet with a cactus will award points to the captor
(`CaptureScore`), and give a penalty to the cactus owner
(`LostScore`). Losing a planet entirely gives a different penalty
(`DeadScore`).
**If `KeepCactus=No`,** the cactus will be destroyed and that's it.
**If `KeepCactus=Yes`,** a stump will remain. The stump will continue
producing small amounts of Tequila for the new planet owner and a
penalty for the original builder (`TurnPlusScore`, `TurnMinusScore`,
`TurnOwnerScore`). If enabled (`RebuildCactus`), a new cactus can be
built atop the stump.
Capturing a stump does not give any points.
Building a cactus is therefore worthwhile if you are sure to keep that
planet long enough that it produces more Tequila than you'd pay for
losing it.
### Cactus Status
You will receive a list of your cactuses each turn. Each cactus has
one of the following statuses:
* cactus: it's a full cactus that produces `TurnScore` per turn;
* foreign: it's the stump of a cactus someone else built. You get
`TurnPlusScore`, the builder gets `TurnMinusScore`;
* stump: it's the stump of a cactus you built, someone captured it,
and you captured it back. You get `TurnOwnerScore` each turn;
* exile: it's the stump of a cactus you built that someone stole. You
get `TurnMinusScore`, current owner gets `TurnPlusScore` (this is
the opposite of "foreign").
Voting Rules
------------
Agave Tequilana can be used to determine the end of a game if enabled
with `EnableFinish` (default).
Starting at `VoteTurn`, players can vote. Each player's vote is worth
their number of planets, plus number of cactuses controlled (i.e.,
planets with a cactus count double). The game ends when more than
`FinishPercent` of all votes want the end.
To vote for the end of the game, send a message
cactus: vote yes
to yourself. A vote is "sticky" and will be applied for this and
future turns. To retract a vote, send a message
cactus: vote no
You cannot vote for the end of the game while you are still building
cactuses. Any `build` command (temporarily) invalidates a `vote yes`.
Alternatively, the game will end when someone reaches `FinishScore`.
Friendly Codes
--------------
+ `con` (configuration; planet friendly code)
Agave Tequilana reacts to the `con` friendly code by sending you the
current configuration settings as a set of subspace messages.
Classic Message Processing
--------------------------
The "official" way to give commands is to use the `cactus:` prefix.
When the `ProcessMessages` option enabled (default), Agave Tequilana
will emulate Cactus2001 by also reading "normal" player messages a
player sends to themselves. When PHost is being used, these need to
start with a '<' marker, but otherwise do not require a prefix:
<Command:>
defhw 13
(or `build 13`) will a cactus on planet 13. In addition, forwarding a
planet to yourself in VPA will also cause a cactus to be built:
<<< VPA Data Transmission >>>
OBJECT: Planet 13
The 'vote' command is also recognized this way.
Unlike "official" command messages, these messages will echo back to
you.
Host Order
----------
### AUXHOST2 (after movement)
+ Config transmission: process all `con` friendly codes and send
messages;
+ Command processing: process all commands;
+ Cactus building: cactuses are built in planet Id order, the order in
which you send the commands does not matter. If a cactus cannot be
built, it is retried (this can happen rarely, if player A builds a
cactus over B's stump and therefore frees a slot for B);
+ Score updates;
+ Vote processing;
+ Status reports.
Known Differences to Classic Version
------------------------------------
If you lose a planet the same turn you try to build a cactus, the
build attempt will fail in Agave Tequilana. In Cactus2001, the cactus
will be built and immediately be captured.
In Agave Tequilana, building a cactus always has precedence over
voting "yes". In Cactus2001, it depends on the order in which commands
are received.
Agave Tequilana tries to build cactuses in planet Id order,
independant from the order of commands. Cactus2001 builds cactuses in
the order it receives commands in.
Configuration
-------------
### General
+ `KeepCactus` (boolean, default: `False`)
When enabled, a stump remains after capturing a planet. When
disabled, the cactus will be destroyed.
+ `ProcessMessages` (boolean, default: `True`)
When enabled, also process messages not sent through the regular
Command Processor interface; see "Classic Message Processing" above.
If this feature makes problems, it can be turned off with this
option.
### Scoring
+ `TurnScore` (integer, default: 1)
Score given to the owner/builder of a cactus every turn.
+ `TurnOwnerScore` (integer, default: 1)
Score given to the owner of a stump when they were the one who built
it (i.e. someone captured it and they captured it back). Only
relevant when `KeepCactus=Yes`.
+ `TurnPlusScore` (integer, default: 1)
Score given to the owner of a stump they did not build (i.e. they
captured it). Only relevant when `KeepCactus=Yes`.
+ `TurnMinusScore` (integer, default: -1)
Score given to the builder of a stump that someone else owns (i.e.
captured). Only relevant when `KeepCactus=Yes`.
* `CaptureScore` (integer, default: 10)
Score given to the player who captures a planet with a cactus.
+ `LostScore` (integer, default: -15)
Score given to the player who loses a planet with a cactus.
+ `DeadScore` (integer, default: -25)
Score given to the player who loses a planet with a cactus entirely,
i.e. planet becomes unowned.
### Building
+ `NeedBase` (boolean, default: `False`)
If enabled, a cactus can only be built on a planet that has a starbase.
+ `RebuildCactus` (boolean, default: `False`)
When enabled, a cactus can be built on a planet that has a stump.
When disabled, the stump remains for the remainder of the game.
Only relevant when `KeepCactus=Yes`.
+ `ClansRequired` (integer, default: 0)
Minimum number of colonist clans required to build a cactus.
+ `CactusLimit` (integer, default: 0)
Maximum number of cactuses each player can build. Stumps count
against that limit even if the player who built them does not
currently control them.
The default value 0 (can also be spelled `No`) means the number of
cactuses is not limited.
+ `CostAdditive` (integer, default: 0), `CostMultiplier` (integer,
default: 0), `CostPower` (integer, default: 0)
Determines the cost of a cactus, as
CostAdditive + CostMultiplier * Num_built_cactuses^CostPower
Examples:
- CostAdditive=0, CostMultiplier=0, CostPower=0 (default): building
cactuses does not affect the score;
- CostAdditive=7, CostMultiplier=0, CostPower=0: every cactus costs
7 points;
- CostAdditive=0, CostMultiplier=1, CostPower=1: arithmetic
progression, first cactus is free, second costs 1, third costs 2,
fourth costs 3, etc.
- CostAdditive=0, CostMultiplier=1, CostPower=2: square progression,
first cactus is free, second costs 1, third costs 4, fourth costs
9, etc.
In the formula, `Num_built_cactuses` is the number of currently
existing cactuses built by the player, including stumps currently
under other players' control.
+ `MinScore` (integer, default: -32768)
Minimum permitted score. If a cactus has a cost greater than 0, it
is not allowed to reduce the score below this value.
This option should be configured to a negative value. Because scores
start out as 0, players need some credit to build the first cactus.
Losing score from, for example, `CaptureScore`, is not limited and
can reduce the score below the limit.
### Voting
+ `EnableFinish` (boolean, default: `True`)
If enabled, Agave Tequilana can be used to determine the end of a
game, either by voting, or by reaching a score goal. The following
parameters are only handled if this option is enabled (default).
When disabled, `vote` commands are silently ignored and the
following parameters have no effect.
+ `VoteTurn` (integer, default: 65)
Votes are accepted for the first time at this turn.
+ `FinishPercent` (integer, default: 66)
Game finishes if this percentage of the given votes approve the end.
+ `FinishScore` (integer, default: 2000)
Game finishes when one player reaches this many points.
Utility Data Files
------------------
Agave Tequilana will generate `utilX.dat` records.
### Player score (type 51)
This record is defined by PHost to be used for score reports. Agave
Tequilana sends three copies of it.
50 BYTEs Name; player-readable description of this score.
WORD Identifier
16544 Number of owned cactuses
16545 Number of built cactuses
16546 Score
WORD Turns-over-limit required to win, sent as -1.
DWORD Win limit. For the score, same as FinishScore,
otherwise, -1 for none.
11 DWORDs Scores for each player. -1 if not known. Negative scores
are reported as 0.
### Your score (type 16544)
This record is sent every turn and reports your score. It also serves
as a marker that this add-on is present.
32 BYTEs Name and version of add-on, "Agave Tequilana 0.42"
WORD Number of owned cactuses
WORD Number of built cactuses
WORD Score (can be negative)
WORD Vote flag
### Cactus (type 16545)
This record is sent every turn, for every cactus you built or own.
WORD Planet Id
WORD Type
0 Cactus
1 Foreign stump (someone else built, you own)
2 Exile stump (you built, someone else owns)
3 Stump (you built and own)
PlanetsCentral
Version 20240229
