EnglishStyleGuide - 0ad - Wildfire Games

0ad/0ad

Fork 16

Table of Contents

Orthography

Common mistakes
English spelling
Calender years
Dynastic factions
Greek and Latin

Terminology

Actions
Cursor vs Mouse
GUI
Stats
Structures
Units

Tooltips

Auras
Technologies
Templates

Typography

Capitalization
Punctuation and spacing
Unicode

External links

For specific (i.e. non-English) name strings, see SpecificNames. For translations into other languages, see [Localization](Localization#AdditionalInstructionsforLanguageTeams).

This guide provides some ground rules to write user-facing texts for 0 A.D.

Orthography

Common mistakes

Always check what you type!

There is only one t in eighteen.
While four and fourteen are written with ou, there is no u in forty, only an o.
The verbs to an-, de-, and pronounce are always spelled with ou, as are the nouns an-, de-, and pronouncement, whereas the nouns an-, de-, and pronunciation are spelled with only u.
Although the word full ends with double ll, adjectives ending in -ful (e.g. forgetful, resourceful, useful) have only one final l.
Words such as developer and exceptional are written with one p or n, respectively (unlike in French).
The verbs loose and lose have very different meanings. See also https://www.lexico.com/grammar/common-misspellings

English spelling

Use American English spelling.

American	Oxford	British
advice (noun)\advise (verb)	advice (noun)\advise (verb)	advice (noun)\advise (verb)
license (noun and verb)	licence (noun)\license (verb)	licence (noun and verb)
practice (noun and verb)	practice (noun)\practise (verb)	practice (noun)\practise (verb)
American	Oxford	British
---	---	---
analysis	analysis	analysis
analyze\analyzing\analyzable	analyse\analysing\analysable	analyse\analysing\analysable
archeology	archaeology	archaeology
artifact	artefact	artefact
center	centre	centre
civilization *	civilization *	civilisation *
color	colour	colour
defense	defence	defence
dialog	dialogue	dialogue
enroll	enrol	enrol
fertilizer *	fertilizer *	fertiliser *
gray	grey	grey
itemize *	itemize *	itemise *
jailor	jailer	gaoler
maneuver	manoeuvre	manoeuvre
northeast(ern)	north-east(ern)	north-east(ern)
plow	plough	plough
setup (noun)\set up (verb)	set-up (noun)\set up (verb)	set-up (noun)\set up (verb)
skeptic	sceptic	sceptic
traveled\traveling\traveler	travelled\travelling\traveller	travelled\travelling\traveller
American		British
---	---	---
corn		maize
counterclockwise		anticlockwise
eggplant		aubergine
fall		autumn
sidewalk		pavement
zucchini		courgette

Oxford spelling is used by many international organizations (e.g. ISO, NATO, UN, WTO, WWF) and some academic publications (notably Oxford University Press and Cambridge University Press, whereas the University of Oxford and the University of Cambridge use British spelling).
The -ize/-ise, -izer/-iser, and -ization/-isation differences only apply to words where the ending is not part of the root.
- Some words always end in -ise in all varieties of English. These are: advertise, advise, apprise, arise, chastise, circumcise, comprise, compromise, demise, despise, devise, disguise, enterprise, excise, exercise, franchise, guise, improvise, incise, merchandise, mortise, premise, reprise, revise, supervise, surmise, surprise, televise, as well as all words ending in -wise.
- Likewise, there are a number of words that always end in -ize in all varieties of English. These include: assize, baize, capsize, downsize, maize, prize, resize, seize, size.
If unsure about the correct spelling, consult a dictionary, e.g. https://www.lexico.com/

Calender years

The name of the game is 0 A.D., which includes dots, for stylistic reasons. However, dots are not used when writing down years. E.g. Augustus was emperor of Rome from 27 BC until AD 14.

good	bad
BC	B.C., BCE, B.C.E.
AD	A.D., CE, C.E.

Also check there is always a single space between the year and BC/AD.

Dynastic factions

singular:	plural:	adjective:
founder of dynasty	members of dynasty	belonging to dynasty
Achaemenes	Achaemenids	Achaemenid
Maurya	Mauryas	Mauryan
Ptolemy	Ptolemies	Ptolemaic
Seleucus	Seleucids	Seleucid

Greek and Latin

Greek words and proper names are Latinized everywhere, except in the specific name.

Latinized	Greek
Aeschylus	Aiskhulos
Darius	Dareios
Plato	Platōn
Seleucus I	Seleukos A'
Thucydides	Thoukudidēs

Also, use the English form if there is one.

English	Latin	Greek
Alexander the Great	Alexander Magnus	Alexandros ho Megas
Aristotle	Aristoteles	Aristotelēs
Athens	Athenae	Athēnai
Homer	Homerus	Homēros
Livy	Livius
Mark Antony	Marcus Antonius
Ovid	Ovidius
Plutarch	Plutarchus	Ploutarchos
Ptolemy	Ptolemaeus	Ptolemaios
Syracuse	Syracusae	Surakousai
Virgil	Vergilius
English	Latin	Greek
---	---	---
Cataphract		Kataphraktos
Hoplite		Hoplitēs
Legionary	Legionarius
Penteconter		Pentēkontoros
Quadrireme	Quadriremis	Tetrērēs
Quinquereme	Quinqueremis	Pentērēs
Theatre	Theatrum	Theatron
Trireme	Triremis	Triērēs

Terminology

In texts that the user needs to understand, such as menu entries, help tooltips, and similar, you must be consistent with the vocabulary that you use.

An object should always be referred to using the same word everywhere in the game, and an action should always be referred to using the same verb. For example, if there is a unit type called ‘Female Citizen’, always refer to it as such, do not also use alternative forms such as ‘females’, ‘women’, and so on. Even in the same paragraph or sentence, you should use the same term.

Always be precise. E.g. if a technology multiplies the melee attack damage of cavalry by 1.2, the tooltip should be “Cavalry +20% melee attack damage”, not “Melee Cavalry +20% attack damage”.

Furthermore, there should be a bijection between descriptions and classes. E.g. if a technology affects the Citizen class, write “Citizens”; if it affects the Soldier class, write “Soldiers”; if it affects only units that have both the Citizen and the Soldier class, write “Citizen Soldiers”.

For specific words that you should use or avoid in 0 A.D. gameplay texts, see the tables below.

Actions

good	bad
build (structures)	construct, make
collect (treasures)	gather
construct (ships, siege weapons)	build, produce, train
gather (resources)	collect, get
research (technologies)
train (human units)	build, construct, recruit, produce

Cursor vs Mouse

Mind the difference between the cursor (virtual) and the mouse (physical).

GUI

good	bad
icon	image, picture, portrait, sprite, thumbnail
window	dialog(ue)

Stats

code		good	bad
`Attack/Capture/Capture`		capture attack strength	capture rate, capture value
`Attack/Capture/MaxRange`		capture attack range	capture range
`Attack/Capture/RepeatTime`		capture attack speed¹	capture rate, capture time
`Attack/Melee/Damage/Crush`		melee attack crush damage	crush, crush attack, crush strength
`Attack/Melee/MaxRange`		attack range	range, melee range
`Attack/Melee/RepeatTime`		melee attack speed¹	melee attack repeat time
`Attack/Ranged/ElevationBonus`		elevation bonus
`Attack/Ranged/MinRange`		minimum attack range	min attack range, minimum range
`Attack/Ranged/RepeatTime`		ranged attack speed¹	ranged attack repeat time
`Builder/Rate`		build rate	builder rate, building rate
`Capturable/CapturePoints`		capture points
`Cost/BuildTime`	structures\ships, siege\animals\other units	build time\construction time\breeding time\training time	building time, production time, recruitment time
`Cost/Population`		population cost
`Cost/PopulationBonus`		population bonus
`Cost/Resources/food`		food cost
`Cost/Resources/wood`		wood cost	timber cost
`Cost/Resources/stone`		stone cost
`Cost/Resources/metal`		metal cost	iron cost
`GarrisonHolder/BuffHeal`		garrison heal rate
`GarrisonHolder/Max`		garrison capacity
`Heal/Health`		healing strength	HP, heal value
`Heal/Range`		healing range	heal range
`Heal/Rate`		healing time	heal rate, healing speed
`Health/IdleRegenRate`	idle	health regeneration rate	regeneration, regen rate, regen speed
`Health/Max`		health	health points, hitpoints, HP
`Health/RegenRate`		health regeneration rate	regeneration, regen rate, regen speed
`Loot/xp`	grant	experience loot
`Looter/xp`	gain	experience loot
`ProductionQueue/TechCostMultiplier/food`	technologies require	food
`Promotion/RequiredXp`		promotion experience
`ResourceGatherer/BaseSpeed`		gather speed	gather rate, work speed
`ResourceGatherer/Capacities/food`		food capacity	carry capacity, foot load
`ResourceGatherer/MaxDistance`		gather distance
`ResourceGatherer/Rates/food.fish`		fish gather rate
`ResourceGatherer/Rates/food.fruit`		fruit gather rate
`ResourceGatherer/Rates/food.grain`		grain gather rate
`ResourceGatherer/Rates/food.meat`		meat gather rate
`ResourceGatherer/Rates/metal.ore`		metal gather rate
`ResourceGatherer/Rates/metal.ruins`
`ResourceGatherer/Rates/stone.rock`		stone gather rate
`ResourceGatherer/Rates/stone.ruins`
`ResourceGatherer/Rates/treasure`
`ResourceGatherer/Rates/wood.rock`		wood gather rate
`ResourceGatherer/Rates/wood.ruins`
`ResourceTrickle/Interval`		resource trickle time
`ResourceTrickle/Rates/food`		food trickle rate
`UnitMotion/WalkSpeed`		movement speed	speed, velocity, walk speed
`Vision/Range`		vision range	line of sight, LOS, vision

Notes:

¹ The meaning in code is reserved from the display text. For example, if code says RepeatTime value × 0.5 (subtract 50%) then the speed will be twice as fast, which should be displayed as +100% (value ÷ 0.5).

Structures

good	bad
Structure	Building
Arsenal	Armoury, Foundry, Siege Workshop, Workshop
Civic Center	Civic Centre, Civil Center, Civil Centre
Dock	Harbour, Pier, Port, Quay, Shipyard, Wharf
Farmstead	Farmhouse, Granary, Mill
Fortress	Castle, Citadel, Fort, Stronghold
Forge	Armoury, Blacksmith, Smithy
House	Dwelling, Home, Hut, Shack
Storehouse	Drop Site, Mining Camp, Storage Pit

Units

good	bad
Cavalry	Cavalry Soldier, Horse, Horseman
Champion
Champion Cavalry	Cavalry Champion
Champion Cavalry Spearman	Cavalry Spearman Champion, Champion Spear Cavalry
Champion Infantry	Infantry Champion
Champion Infantry Archer	Infantry Archer Champion, Champion Archer Infantry
Champion Spearman (both cavalry and infantry)	Spearman Champion
Citizen (cavalry or infantry, female or male)	Worker, Villager, Subject, Slave, Servant, Serf, Peasant, Labourer, Gatherer, Builder
Citizen Cavalry	Cavalry Citizen-Soldier, Citizen-Cavalry, Citizen-Cavalry Unit
Citizen Infantry	Infantry Citizen, Infantry Citizen Soldier, Infantry Citizen-Soldier
Citizen Soldier (cavalry or infantry)	Citizen-Soldier, Soldier Citizen
Female Citizen	Female, Female Worker, Woman
Infantry	Infantry Soldier, Footman
Melee Cavalry	Cavalry Melee Soldier, Heavy Cavalry
Melee Infantry	Heavy Infantry
Ranged Cavalry	Cavalry Ranged Soldier, Cavalry Skirmisher, Skirmisher Cavalry
Ranged Infantry	Light Infantry, Infantry Skirmisher, Skirmisher Infantry, Skirmisher
Ship	Boat, Craft, Vessel
Siege Engine	Siege Weapon, Siege

Tooltips

In general, start with a capital, end each statement with a full stop, and capitalize classes.

Auras

Auras are JSON files located inside simulation/data/auras/. Auras are temporary, their effects disappear when the aura entity is lost. The shared format for the auraDescription is: "player class change attributes requirements":

player: if and only if an affectedPlayers entry is specified; by default auras affect only their own player. Other options are (Player.js):
- Ally: player is our ally → Allied and Own
- ExclusiveAlly: player is our ally excluding ourself → Allied
- MutualAlly: player is our ally, and we are its ally → Allied and Own
- ExclusiveMutualAlly: player is our ally, and we are its ally, excluding ourself → Allied
- Enemy: player is our enemy → Enemy
class: the affected class(es), e.g.:
- "Citizen Infantry" → Citizen Infantry
- "Siege", "Structure" → Structures and Siege Engines
change: the actual modifications, e.g.:
- "replace": 0 → have 0
- "multiply": 1.1 → +10%
- "multiply": 0.85 → −15%
- "add": 1 → +1
- "add": -25 → −25
attributes: the modified stats; see above
requirements: if and only if a requiredTechnology is set; specifies the genericName of the required technology; e.g.:
- "pop_wonder" → (requires the “Glorious Expansion” technology)

The exact format depends on the aura type (see Auras.js):

type	format	examples
formation	player class in his formation change attributes requirements	Soldiers in his formation +3 crush, hack, pierce resistance, +15% movement speed. (ref)
garrison	player class he is garrisoned in change attributes requirements	Ship he is garrisoned in −30% batch training time and +50% movement speed. (ref)
garrisonedUnits	Garrisoned player class change attributes requirements	Garrisoned Siege Engines +3 health regeneration rate. (ref)
global	player class change attributes requirements	Allied Structures −20% technology research time. (ref)\Temples −25% stone cost and +2 garrison heal rate. (ref)\+40 maximum population limit (requires the “Glorious Expansion” technology). (ref)
range	player class change attributes requirements	Workers +25% grain gather rate. (ref)\Own and Allied Soldiers and Siege Engines +1 capture attack strength, +20% melee and ranged attack damage. (ref)\Champions +2 capture attack strength, +20% melee and ranged attack damage, +10% movement speed. (ref)

Technologies

Technologies are JSON files located inside simulation/data/technologies/. All technologies are global and irreversible. Please follow the "player class change attributes" format (see auras above, without requirements), e.g.:

"tooltip": "Soldiers +2 hack resistance.", (soldier resistance)

Templates

Entity templates are XML files located inside simulation/templates/. They can have a string inside the node, to summarize what makes them unique. Be brief and precise. A few examples:

Resource supplier: <Tooltip>Catch fish for food.</Tooltip> (fish)
Structures: <Tooltip>Construct Siege Engines and research Siege Engine technologies.</Tooltip> (arsenal)
Units: <Tooltip>Garrison units for transport and to increase firepower.</Tooltip> (siege tower)

Typography

Capitalization

Use title case for:

button captions;
entity classes;
entity and technology names (generic and specific names);
key names;
proper names. For everything else, don't capitalize:
cardinal directions (north, east, south, west), unless part of a name;
resource types (food, wood, stone, metal);
damage types (crush, fire, hack, pierce, poison);
other stats (e.g. attack time, territory influence radius, vision range);
actions (e.g. attack, click, move, select, send).

And never use full capitalization (e.g. THIS).

good	bad
Click the Citizen Soldier icon	Click the CITIZEN SOLDIER icon
Hold Shift and click	Hold shift and click

Punctuation and spacing

A serial comma is used when listing three or more items. E.g. “Available to Britons, Gauls, and Iberians.” or “Capture, Melee, or Ranged.” and not “Britons, Gauls and Iberians.” or “Capture, Melee or Ranged.”
Only use one space, not two, after a full stop to end a sentence.
Do not use spaces before “large” characters (e.g. ?, !, :, %).
There are three options for parenthetical remarks:
- parentheses (which have spaces on the outside, but not on the inside) are preferred;
- en-dashes – which have spaces both inside and outside – can also be used occasionally if it looks better;
- em-dashes—which have spaces neither inside nor outside—are better avoided.
Use “English-style” quotation marks, not « French-style » or „German-style“ (nor the other »German-style«).
Please read the articles listed at https://www.lexico.com/grammar/punctuation

Unicode

We have a somewhat complete Unicode support, do not limit yourself to ASCII and learn how to use Unicode input in your system.

good	bad	usage
… (U+2026, ellipsis)	... (three full stops)	intentional omission
• (U+2022, bullet)	- (hyphen)	itemization
– (U+2013, en-dash)	- (hyphen), -- (two hyphens)	range of values (500–1 BC), oppositions (Greco–Persian wars)
— (U+2014, em-dash)	- (hyphen), --- (three hyphens)	attribution of a quote source
− (U+2212, minus)	- (hyphen)	subtraction, negative values (−20% training time)
× (U+00D7, times)	x (X)	multiplication
“ (U+201C)	" (programmer's quote)	start of a quotation
” (U+201D)	" (programmer's quote)	end of a quotation
‘ (U+2018)	' (apostrophe)	start of a quotation inside a quotation
’ (U+2019)	' (apostrophe)	end of a quotation inside a quotation

Use the ordinary hyphen or hyphen-minus (-) for:

hyphenation;
compounds (Greco-Bactrian kingdom);
negations (non-starter);
vowel separation (de-escalate);
to distinguish between varied meanings. For more examples, see https://www.lexico.com/grammar/hyphen