Find User here you can look for a user

Introduction to Flags and Scripting

My Colony 2 v0.23.0 introduced the new Flag/Scripting system. This is being implemented primarily to support the in-game tutorial dialogs, but also contains features which will allow it to go well beyond this. This thread gives a basic overview of the system and how mod creators can use it in their own project.

As you might have guessed, the system is comprised of two base components, Flags and Scripts, with each script containing a collection of Actions that the engine can perform. When the player does something to trigger a flag, the engine will look through all of its scripts to determine if one or more of them are triggered by the flag. If it finds any available scripts, it will then run through their actions in sequential order.

Player and Global Flags

There are two types of flags, Player and Global. Player flags apply only to the player who activated them, so that any script they trigger will only impact them. This also means that the flag can be triggered by each player. Global flags apply to the entire game world and can only be triggered once, so that the first player who triggers a global flag will activate it for all. A player flag can only be triggered once per player, and a global flag can only be triggered once per world. The exception to these is if a Clear Flag action is triggered in a script.

A sample use case for a player flag is an in-game tutorial message. Suppose the player builds a refinery and you want to show a message about the refinery once it's built. You wouldn't want that message to show up to everybody, so a player flag here would be appropriate.

A sample use case for a global flag could be a scenario where the first player who builds a specific building gets to unlock a free tech, but only the first person to do so gets it.

Setting Flags

There are currently four main ways to set game flags, although more may be added in the future.

Flags can be set when a player joins the world. There are two places you can set these flags. First is in the World object in the game editor. Any flag specified here will automatically play when the player joins, no matter what their civilization is. You can also set this flag in the Civilization object. Here the flags will be triggered when the player joins the world, if they are using the specified civilization.

Next flags an be set when a new unit is created, and these flags are specified in the Unit object in the game editor. These will also be triggered with any free units the player starts out with at the beginning of the game, so they can also double as a "player joins world" flag.

Moving on, flags can be set when a new structure is built. As you might have guessed, these can be set in the Structure object in the game editor.

Finally, flags can also be set within script actions themselves. Allowing you to chain scripts by having one script call another through flag setting.

Creating Scripts

The scripts section in the game editor is where you create your different scripts and specify their actions. Scripts are made up of three parts, a Reference Name (which is just used to identify the script in the game editor so you don't get them confused), a Trigger Flag (which is the flag used to start the script) and an Actions List.

The Actions List is where all of the... action is. A script can contain how every many actions you deem necessary, and the script will play each action in order, one after the other. There are a handful of action types to choose from, ranging from playing messages to setting/clearing flags to giving things to players, and so on. All of the actions are fairly self explanatory in the game editor.

The Future

I think that the Flags and Scripting feature has a lot of potential for the future of MC2 and its related mods, and I am open to suggestions on how to improve this system going forward. More trigger events and more action types are absolutely on the table, so if you are developing a mod using this system, please let me know here on the forums what you would like to see added.

I was thinking that it might be helpful, along with Flags and Scripts, to also add Variables to the mix, both player and global. So a script could set a name or number to a variable and call on that later on. There could then perhaps be conditional actions, based on those variables. That is just one thought, really the possibilities are endless!

So there it is, that is what is in the scripting system so far. Let me know what you think, what questions you have, and what improvements can be made. This system will only get better and more advanced as time goes on!
Owner of Ape Apps, LLC
@bastecklein Bit late, but might there be support for time- or RNG-based flags in the future to simulate phenomena such as weather or asteroid impacts?
sometimes I make stuff
Ape Apps, LLC is an independent software development company founded in 2010 by Brandon Stecklein. Over the years, Ape Apps has published over 400 apps and games across various platforms. You can get in touch with Brandon on Twitter or by leaving a post on his wall @bastecklein
App of the Day