Introduction
An introduction to scripting Company of Heroes 3 with LUA and SCAR.
Overview#
Scripting in Company of Heroes 3 involves being familiar with two main concepts: LUA and SCAR.
Understanding how these systems work in relation to the game is essential to beginning to make scripts for your Company of Heroes 3 mods.
The three sections below are quoted from Relic Entertainment’s modding knowledge center.
What is LUA?#
LUA is a lightweight programming language designed to be embedded in other applications. This language has seen frequent use in game development across the industry for its flexibility, execution speed, and ease-of-use for integrating it into game engines.
If you already know how programming languages work, there are a few main things you might find different with LUA:
- LUA is Dynamically Typed, meaning that variables can be reassigned to different types on the fly. The function
scartype()returns the type of a variable.- There are 8 basic types in LUA, but Age of Empires IV only uses 6 of these. They are: nil, boolean, number, string, function, and table.
If you are unfamiliar with programming languages and would like to create your own Crafted Map scenarios or Game Modes for Company of Heroes 3, it is recommended you start by learning LUA.
There are multiple resources online to begin your journey, including on the official LUA website.
The mention of Age of Empires IV above is Relic’s own; the same six types apply in Company of Heroes 3.
What is SCAR?#
SCAR (short for “Scripting At Relic”) is a programming language based on LUA that can run during a match in Company of Heroes 3.
SCAR is the result of integrating LUA into the Company of Heroes 3 Essence Editor, combined with a number of custom functions that allow for easy modification of game objects and parameters.
This means if you are familiar with how to script in LUA, you also know how to script in Company of Heroes 3.
By using your LUA knowledge to explore Company of Heroes 3’s built-in SCAR functions, you should be able to spawn and command units, set objectives, destroy buildings, and a variety of other core functions.
Company of Heroes 3 employs SCAR in a variety of uses, including creating:
- Multiplayer game mode logic
- Campaign missions
- Procedural map generation
- Debug functions
SCAR is useful in these situations because of how it works, as it runs at a “global” level.
With SCAR, there is only a single script running which can be doing multiple things, allowing it to preside over the entire game session. This makes SCAR perfect for using in content such as scripted missions or custom game modes.
Where to go next#
This site documents the SCAR library itself — every function, enum and global the game exposes to scripts.
- All functions — browse by category, or start here if you are not sure what you are looking for.
- Globals — the values the game defines before your script runs.
- Glossary — what each attribute on a function page means.
If you already know the name of what you need, search is the fastest route: press Ctrl + K (or ⌘ + K) anywhere on the site.
About ScarDoc#
scardoc.cohbattlegrounds.com is a project by the CoH: Battlegrounds Development Team. It is unofficial, and not affiliated with Relic Entertainment.
The reference is produced by our scardoc-generator tool, which reads the game’s own SCAR sources. The tool is being actively worked on, and the list of functions is updated whenever a new build of the game is released.
As a community project it is susceptible to errors, missing functions and related issues. If you run into one, tell us about it — that page covers where to report what, and how to contribute.