[MOD] Single-player mechanics

Overview

Want to script an interesting, full-of-action single-player mission? Here you can find a description of tools you can use

Before you start

To be able to use information from this guide you will need to have a single-player map with basic setup. You can find an instructions for creating it HERE. You should be able to launch your map from the editor (Play In Editor) to make process of creating a map possible. Use Play button in the editor, remember to have Number of Players set to 1, you should be able to build buildings in your base and move your units, assuming you have correctly set up Player Starts. More info about that can be found HERE.

You probably also want to have some Villages and Resource Points on your map, because they are the main way to obtain resources in the game – you can find a guide for setting up villages and resource points HERE.

Quests

Okay, so first of all, you will probably need to give player some quests. It’s always a good idea to be sure that player has at least one quest active, this way he will know what is his current objective and what to do.

You could use quests from the base game, but we recommend to create your own quests data for your mod map. To be able to do that you will need a DataTable. Add one to your mod content (RMB in Content Browser -> Miscellaneous -> Data Table).

As a base structure for this Data Table select Anc Quest Data stucture.

Good, now we have to configure our level to actually using this Data Table. Open World Settings window and in Anc World Settings tab check the Override Quests DT checkbox and then connect your newly created Data Table to Overriden Qests DT property.

Now, it’s time to create your first quest! Start with something simple to learn the idea behind our quest system, i.e. “Move here”. You need to open your quest Data Table, add a new row (you can do it by clicking a small “plus” button) and fill it with desired data.

Row name: Unique ID for this quest, not visible for the player.
Is Side Quest: Whenever this quest should be not mandatory to complete, it will be shown with different font color.
Quest Name: Big quest title that will be shown to the player for a few seconds upon quest activation.
Quest Text: Quest summary visible to the player all the time quest is active.
Auto Save on Deactivate Success: Should the game perform auto-save on the quest completion?
Auto Save on Deactivate Fail: Should the game perform auto-save on the quest fail?
Auto Save on Update: Should the game perform auto-save when the quest is updated?
Marker Texts: Texts visible above quest markers on the level.

Before jumping to the Level Blueprint we will need one more thing: Quest Marker. Find it in Content Browser (Blueprint’/Game/Blueprints/Game/BP_Anc_QuestMarker.BP_Anc_QuestMarker’) and place it on the level.

So, now with quest data setup done, it’s scripting time!

Open Level Blueprint, this is the place where all of the magic is done. For activating the quest you should use Activate Quest node on Anc Player Controller. You can do it for example a few seconds after the level start, for this purpose use Event Game Started. Important: Do not use Begin Play in Level Blueprint! We are still loading assets after Begin Play, so the real game starts for the player is when Event Game Started is fired.

Target: Use Anc Get Local Controller.
Row name: Quest row name (unique ID) from Quests Data Table you have created before.
In Quest Markers: Array with references to Quest Markers on level you would like to use for that quest. You can have one Quest Marker like on this example, multiple ones, or none – for this purpose use 0 elements array (remove pin on Make Array node).
In Param X: Initial values for the quest parameters. Usage of quest parameters will be described below.
Water Progress: Values from 0 to 1 will cause bar with water progress to appear with the quest text (mechanics used on some of the Saracens levels).

At this point when you start game you should see your quest becoming active after an initial delay.

For deactivating quest use Deactivate Quest node. In this example we are doing this after detecting player’s squad entering the Trigger Volume (for that purpose use OverlapOnlySquad collision preset on volume). Player’s squads will have the same Player Index as Desired Player Index of player’s Player Start (is AI Controlled set to false), which typically will be 0.

Target: Again, use Anc Get Local Controller.
Row name: Quest row name (unique ID) from Quests Data Table of the quest you want to deactivate.
Failed: Set to true if you want to fail the quest. Set to false if you want to pass the quest.

That’s how most of the quests in Ancestors Legacy are created. There are some advanced options however, probably most useful of them is possibility of having Quest Parameters. You can use them for creating counters in your quests, i.e “Villages to capture: 3”, “Enemies killed: 3 / 5” etc.

To use Quest Parameters you have to have proper Quest Text in your Quest Data Table. Use following character codes for marking parameters in your Quest Text: {0}, {1}, {2}, {3}. Number in parenthesis identifies the parameter number, 0 being the first one. So, for our examples Quest Texts should look like these: “Villages to capture: {0}”, “Enemies killed: {0} / {1}”.

When activating quest with parameters the only thing you do differently is initializing the values of parameters and adding more Quest Markers, if you need them.

Last thing you will need for handling Quest Parameters is Update Quest node. You can use it for changing parameter values and Quest Markers active for that quest.

In Param ID: ID of parameter (number in parenthesis) you would like to update.
In Val: New value of specified parameter.
In Quest Markers: Array of Quest Markers you would like to perform action on, type of that action is determined by the next Update Quest node parameter:
Update Mode: This enumeration value determines what will happen with In Quest Markers, there are three options:

• Add: Use this option if you want to add some Quest Markers to the quest.
• Replace Existing: By selecting this option you will replace quest’s current active Quest Markers for Quest Markers specified in In Quest Markers array.
• Remove: This option will cause Quest Markers from In Quest Markers array to be removed from this quest.

Dialogues

If you want to create a story-focused mission or just add a little bit of life to your level, then you will need dialogues.

So, create a data table based on Anc Speech Data structure and fill it with some dialogues data.

Row Name: Dialogue unique ID, not visible to the player.
Speech Wave: Audio file of the dialogue; don’t worry, you can leave that property empty if you would like to have text only dialogues.
Character: Who will be saying this dialogue line; you can find possible speakers in this data table: Content/Blueprints/Datatables/DT_StoryCharacterData
Unfortunately adding new speakers is not that simple and requires changes in base content and game code.
Text: Dialogue text.
FaceTextureCache and SpeechWaveCache: ignore these ones, they will be filled automatically when/if needed.

Then you need to set Speech Map DT property in Anc World Settings to your data table.

Now you are ready to script showing some dialogues. In order to do that we have to go to the Level Blueprint and use M_AddSpeech macro.

Color: Color of character’s name font. 0 stands for blue (player), 1 stands for red (enemy), 2 stands for green (ally).
Time: How long dialogue widget should be visible on screen. This value is used only when dialogue line doesn’t have audio wave.
Speech Name: Dialogue ID, that is Row Name from previously created data table.
Add Sound mix: Leave this one checked if you want all game sounds and music to be a little quieter during playing a dialogue speech wave (will have no impact if the dialogue has no corresponding speech wave).

And that’s it! You can add multiple dialogues after each other in the same tick, there is a queue system which will play them one by one.

Map finish

In single-player mission at some point you’ll need to cause map ending – either positive or negative one.

To make this happen you should firstly prepare Data Table with loose/win explanations/descriptions visible to the player after finishing/failing the mission. Create a Data Table based on Anc Win Lost Explanation structure.

Row Name: Map finish explanation’s ID, not visible to the player.
Explanation: Well… an explanation of map’s finish/fail 😉

Then you need to setup your level to use explanations from your Data Table, not a base one. Go to World Settings, check Override Win Lost Conditions DT flag and set up property Overriden Win Lost Conditions DT to your Data Table.

Great, your basic setup is done! Now, only thing to do is script your map endings. Of course a place for doing that is Level Blueprint. You have to use F Finish Campaign Map node.

Has Won: Using this bool you can determine if this node will cause level fail or rather level success ending screen.
Row Name: Explanation’s ID, which is Row Name from expanation’s Data Table.

And that’s it!

Basic AI scripting

In case you want to script some behaviours for game characters here you can find some basic information about tools and ways to achieve that.

Often you will need to have reference for AncSquad object in order to do something with it – the easiest way to get it is from BP_Anc_SpawnPoint, event SquadSpawned – look HERE for more details and information on Spawn Points. Of course scripting of the signle-player missions by default takes place in Level Blueprint.

The simplest and probably most useful thing to script is basic movement. If you want to order a enemy/ally squad to move into a specific location you should use AI Move To node, which is a function in code in AncSquad class.

Target: AncSquad object you want to move.
Destination: Where squad should be heading.
Rotation: Squad will rotate themself in this direction after reaching the movement goal.
Max Speed: How fast can go (will not cause squad to move faster that its maximum speed determined from its statistics). -1 will has no effect on squad movement speed.
Reset: Check if you want squad to stop everything it is doing and immediately proceed to this movement order, leave uncheck if you want to queue this movement order.
Command Index: We highly recommend to leave default value of -1 here ^^
Can be Aborted: Uncheck if you want to make this order non-abortable – use with caution and at your own risk!
No Voicover: Check if you don’t want voiceover order confirmation to be played.

There is also other way of giving a movement order to a squad – more convenient if you have a movement target placed on level. Node is called F AI Move To Actor.

Using this node you can give an order of attack to a squad. It works the same way as if you would right click on an enemy, it simulates RMB click – so archers will run towards target and start shoot when target is in ragne, melee units will run as long as they enter combat.

Target: Squad you want to give attack order to; the attacker.
Target Actor: Target of the attack, the victim. Could be another AncSquad object, or AncBuilding object. Make sure it has different Team Index than attacking squad.
Is Charge Allowed: Unchecking this boolean will block charges if attack target is another squad.
Reset: Analogously as in AI Move To node this variable determines if the order will be executed instantly or put in orders queue.

If instead of giving specific orders you rather would have squad doing and acting on its own, you could enable its single-player AI. There are two ways of doing that: in a Spawn Point or in blueprint. First method is described in the Spawn Points guide (HERE). For enabling a single-player AI on squad in blueprint you need to call Pause Squad AI function on target squad.

Target: Squad you want to enable/disable single-player AI on.
Pause: Determines if single-player AI should be paused (turn off) or active on target squad.

Important: Be sure to not enable AI on player’s squads 😉

Objective cutscene

Maybe you have noticed, in Ancestors Legacy missions there are plenty of mini-cutscenes, when camera are moving back and forth above the level showing the key locations player will need to focus on. We have developed a system for quick and easy setup of those kind of cutscenes, which works very well if you add some AI movement and dialogues.

Say hello to F Objective Cutscene node! Calling this function will start mini-cutscene, you as a scripter will take control over player’s camera, input and HUD will be disabled. All objective cutscenes are skippable.

This might look scary at the first glance, but the main idea is this: camera will be travelling sequentially to each actor from Actors to Show array and stay there as long as corresponding entry from Duration per Actors array will determine.

Actors to Show: Array of actors camera will be travelling to. We usually use Notes or Target Actors for this purpose, as they are very simple actors invisible to the player. This array has to be the same length as Duration Per Actors array.
Camera Height: How high above the ground camera will be located during the objective cutscene.
Distance to Actors: Distance between targeted actor and a camera. You can use this and previous parameter to tweak camera position above the actors.
Blend times: How long (in seconds) will take to move camera from one target actor to another.
Duration Per Actors: How long (in seconds) will camera stay above each corresponding target actor. This array has to be the same length as Actors to Show array.
Rotation Speed: Speed of camera rotation while floating above the target actor.
Move Down Speed: Speed of camera down movement while floating above the target actor.
Blend After Skip: Time of camera movement to the end actor if cutscene will be skipped.
Look at Actor on End: Actor camera should travel to on cutscene finish (after last actor from Actors to Show array or after skip).
Camera on Targets: Event called every time camera movement to the target actor is completed, index of that actor in Actors to Show array being the parameter. To create proper event just drag the link from this pin and choose Add Custom Event option.
Cutscene Ended: Event called at the end of a cutscene, parameter telling you if cutscene was skipped or not. Create Custom Event the same way as for the Camera On Targets pin.

Fog Of War Logic True: During objective cutscenes Fog of War visual effects are turned off, but FOW logic still applies: that means units i.e. too far away from your forces will be invisible. Uncheck this boolean to change this behaviour and show everything during the cutscene.
Is on Game Started: Mark this as true if you are starting objective scene at the very beginning of the level. Remember, don’t use Begin Play, but Event Game Started instead!

And that’s all! If you feel overwhelmed, just start by filling up Actors to Show and Duration Per Actors arrays and create events (it’s necessary for level blueprint to compile, even if you won’t use this events), only after having that sorted out play around with the rest of the parameters. Good luck!