Company of Heroes 3 - Playbill Visual Scripting Tool

Company of Heroes 3 is a AAA real-time strategy game set in the Mediterranean theatre of WW2, focusing on intense tactical combat in fully destructible environments. Strategic choices come to the forefront in this installment with the addition of the Italian Dynamic Campaign, allowing players to approach RTS Missions how they choose and tell their own stories.

On this project I was a Campaign Designer. I filled many roles during this game’s 5-year development, but my primary contributions revolved around content and systems on the Italian Campaign Map.

Playbills

The Playbills system was a new visual scripting tool I worked on in pre-production for Company of Heroes 3. I drove its creation based off a project directive to reduce Lua scripting in campaign missions. The bulk of this work was done in the first 6-12 months of development, but ongoing updates were made throughout the project.

My work included:

• Designing the structure for the visual scripting tool

• Lua scripting reusable Conditions and Actions commonly used in missions

• Identifying and prioritizing engine improvement tasks for the tools/core tech team

Prefabs

The playbills system was built using a proprietary tool called Prefabs. Prefabs in this context are prepackaged bits of Lua script with exposed variables that can be placed as an instance in the game level and tuned through customizable UI.

The prefab instance is placed in the world (green), then variables are tuned in the properties window (purple).

Early uses for this system were smaller in scope than a full visual scripting tool, but they allowed designers to prepackage commonly used mission elements like enemy spawners and AI encounter logic. My aim for Company of Heroes 3 was to push this system further by allowing designers to script missions entirely using prefabs.

An early prototype of the Playbills system was made on another project, although that version wasn't integrated with the Prefab UI. That project didn’t move forward with Playbills, however I used its foundation and adapted it to our project’s needs.

How it works

A Playbill’s logic is broken up into a list of Stages that run from top down. Each stage consists of a set of Conditions and Actions. Once a stage is complete it proceeds to the next stage and checks those Conditions and Actions.

The logic flow:

1. Playbills are dormant and won’t run until they are activated.

2. Every activated playbill on the map checks its conditions on an interval.

3. If all conditions are met, then the associated list of actions are run immediately.

4. Once completed, the playbill proceeds to the next stage, if it exists, and repeats.

   
   

Condition and Action Scripting

After the Playbill logic was hooked up to the Prefab UI the remaining work involved scripting the individual Conditions and Actions.

Wait Actions were key to scripting narrative sequences. These delayed subsequent actions in the list from continuing until the wait had completed.

The Conditions and Actions are self-contained functions written in Lua, but they needed to be flexible enough to support all the variables in the Prefab UI. This made the initial scripting of the functions complex but had the huge benefit of reducing common bugs between missions since all logic flowed through the same functions.

The SpawnSquad Action supports complex options reduced to simple checkboxes, like Use Squad Type which allows designers to select from predetermined unit categories rather than specifying individual squads to spawn. Or Spawn Hidden in FOW which picks a spawn location outside the player's view.

Engine Changes

Crucial to the success of this feature were several engineering requests made early in development. I established this list by speaking with other designers around the studio, collating the list of requests, then organizing a review with the tools team to prioritize these tasks based on ease of implementation and impact to designers.

These changes ranged from quality-of-life improvements like hiding parameters not relevant to current variable selection, to key structural changes like allowing variables to be renamed without losing data in missions.

Challenges

Playbills were fantastic at scripted linear sequences but initially lacked in branching capabilities, which were crucial for the more dynamic style of missions we were aiming for on Company of Heroes 3.

Several improvements were made for prefabs to support dynamic gameplay:

1. Condition groups added functionality to check partial completion (e.g., 1/3 complete) and negative completion (if NONE true). This was key in delivering player choice for objectives as well as flexibility for designers.

   

2. Sub-actions were added to individual conditions so even if the whole condition group hadn’t yet been completed, specific actions could still run. This was crucial in delivering feedback for partial completion of an objective.

   

3. Some conditions or actions were given options to hook into metadata variables passed in from the campaign overworld. This allowed designers to script outcomes based on metadata. For example, if a mission was bombed on the overworld map before starting.

Result

The Playbills system was successful in eliminating the requirement for Lua scripting. Hiring was made easier since Lua was no longer a required skill and mission designers were able to ramp onto the project much quicker. The system was used to ship all the missions, as well as the turn-based campaign map in Company of Heroes 3. Later, the system was released as part of the modding tools accessible to the community.