beyond-all-reason / beyond-all-reason/RecoilEngine

Ally/team terminology is terrible

Open
#1,656 10 comments 3 reactions 0 assignees View on GitHub
area: documentation
Dominant language
C++
Stars
679
Forks
290
Avg merge
3d 2h
Merged PRs (30d)
40

Description

Consider a 2v2v2: A+B vs C+D vs E+F.

Everywhere else when somebody says "team", they mean e.g. A+B.
But in Recoil it means e.g. just A.

When Recoil says that some entities are allied, it can either mean
* A and B are "allied", i.e. belong to the same allyteam.
* A+B and C+D are "allied", i.e. they have a ceasefire.

This is extremely confusing for something that is so basic, especially given how events are set up (if a widget is to only count my own units, it needs to check if they are on "my team"? But I don't want to count my teammates' units?!). The "team doesn't mean team" is the first and biggest idiosyncratic caveat that every aspiring modder has to be told pretty much at the start of their experience.

Then there's minor things like `Spring.SetAlly`, what does it do? Set a team's allyteam? (No.) Set two _teams_ to be allied? (No.) Set two _allyteams_ to be allied aka ceasefired with each other? (Yes, [but actually no](https://github.com/beyond-all-reason/spring/issues/1657).)

----

I'm not sure if this can be approached well. If we add a replacement term then that could result in [even more confusion when there's multiple parallel terms for each concept](https://xkcd.com/927/). But maybe it's still worth trying? Here's a set of hopefully clear terms (using the setup above as an example):
* A is an _army_ (extra neat because that is how SupCom calls it).
* A and B are armies allied in an allyteam (alliance).
* AB and CD are two _ceasefired_ allyteams (alliances).

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the terminology proposal and the linked issue 1657 about Spring.SetAlly, then identify where the team, allyteam, alliance, and ceasefire concepts are exposed. Done would require an agreed terminology scheme and consistent treatment of the affected concepts and API.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.