Notable new features in 1.11.1

[lipk]

The next development release will ship with some nice new multiplayer features. This post explains how you can make use of these enhancements in your add-on, and what you should pay attention to to have your code work properly.

1, Modifications
Starting with 1.11.1, there's a new toplevel tag, [modification] (see ModificationWML). It can be used to get a bunch of [event] tags included in a multiplayer game, without having to bind them to an era or a map. Several modifications can be enabled at a time.

Example:

Code: Select all

#ifdef MULTIPLAYER
[modification]
  id = my_first_mod
  name = _ "My First Modification"
  description _ "A short description for my modification."

  [event]
    name=turn 1
    [message]
      speaker=narrator
      message=_ "Congratulations! You've successfully enabled My First Modification!"
    [/message]
  [/event]
[/modification]
#endif

There's also a new add-on type called "MP modification". To place your add-on in this category, put "type=mod_mp" in the add-on's _server.pbl. Please note that modifications are completely untested with MP campaigns, feedback on that topic is much appreciated.

You should be aware that from now on your eras, scenarios and modifications can be combined with a possibly infinite number of other add-ons. To avoid interference, you'll have to choose your variable names carefully. Always use prefixes, and try to make sure that they're unique. Don't be lazy to utilize long and ugly names for your variables.

2, Options
Eras, multiplayer scenarios and modifications can have an [options] subtag describing user configurable settings for the respective component. Options for the selected era, scenario and enabled modifications are displayed as different widgets on the game creation screen, in a separate dialog accessible through the "Options..." button. The chosen values are saved and stored in WML variables inside the add-on's code.

Example:

Code: Select all

#ifdef MULTIPLAYER
[modification]
  id = my_second_modification
  name = _ "My Second Modification"
  description = _ "My second modification, featuring some options."

  [options]
    [entry]
      id=msm_player_name
      description=_ "Your name:"
      default=_ "John Smith"
    [/entry]
  [/options]

  [event]
    name=start
    [message]
      speaker=narrator
      message=_ "Hello, $msm_player_name!"
    [/message]
  [/event]
[/modification]
#endif

You can find a full reference at OptionWML. Please note that the variables are not accessible before the first prestart event. Unfortunately, currently we don't have a combobox-style option in the lack of a proper widget in the GUI framework, but it will be implemented sooner or later.

As options behave as variables on the WML side, the same coding rules apply here: use prefixes and long, ugly names.

3, Dependencies
The introduction of modifications might cause a radical increase in the number of playable combinations of different add-ons. Careful coding may prevent technical incompatibilities, but it doesn't mean that all add-ons form a sensible combination together. To make it easier for the user to find actually playable compilations, there's now a dependency system between eras, multiplayer scenarios and modifications. For the documentation of the respective keys, see the appropriate sections of EraWML, ScenarioWML and ModificationWML. The game does not only report conflicts but also tries to offer valid combinations, so you need not include any extra instructions with your add-on.

Use the dependency system moderately. Remember, it's made to protect the players from broken games, not to supervise their preferences. For example, if you have an era which radically alters the gameplay, and needs special terrain layout to be playable at all, you can safely claim it incompatible with every map but those which are specifically made for it. As an opposite, the fact that a multiplayer map is balanced only for the factions of a certain era should not be a reason to prevent the user from playing with other factions on it. Of course, there grey zone is wide; if in doubt, the safest option is to be permissive.

Good luck, have fun.

[Dugi]

This is AWESOME! Congratulations, and thanks a lot for it!

Spoiler:

Whoa, my 666th post, and cheering to someone, instead of flaming someone! These guys are right that these forums are so goooood...

[Alarantalara]

Is it possible to add an AI through a modification, so that it could control a faction from any era?

[lipk]

According to my limited knowledge on the topic, AIs can't be set up through events and thus they can't be added by a modification. However, they can already be made independent of eras; when you set a side to "Computer Player", a combobox shows up offering different AIs to choose.

[Dugi]

Will it be possible to use that with single player as well? Like that you don't feel like adding the same event into twenty scenarios, so you just use one [modification]...

[lipk]

Modifications might be expanded to SP at some point in the future, but currently that's not on the todo list (at least not on mine).

Like that you don't feel like adding the same event into twenty scenarios, so you just use one [modification]

That is what you have macros for

[Dugi]

If there is a lot of events that you add to all of them, and a lot of scenarios, it can easily take minutes to load and consumes hundreds of megabytes of RAM. In the case of my campaign, it took two minutes to load and ate more than a gigabyte of RAM (well, almost two, but it removed some stuff from the RAM after that it occupied about 1.5 GiB).
I am using an imitation of [modifications], I placed the events into a unit that is created and killed in the prestart of each scenario, to inject the events there without preprocessing them too many times, and [modifications] working for singleplayer would make this much easier.

Or is it hard to add that into singleplayer, too different from multiplayer?

[Pentarctagon]

How would using modifications change that? The same events would still be added to the scenario.

[Dugi]

The problem is preprocessing. If there is a macro, these events are placed into every scenario and loaded into the RAM. If there are added by the unit (or, ideally, modifications), they are preprocessed only once and added into the scenario when the unit is created (or ideally when modifications apply). This may appear to be nothing, but for me it is a difference between 100 MiB of RAM consumed and 2 GiB or RAM used.

[lipk]

Or is it hard to add that into singleplayer, too different from multiplayer?

Although the single player part of the game is generally more polished than the multiplayer one, the latter has a clear advantage at one point: it has facilities to compile the game data from multiple sources. Implementing support for modifications was in fact a rather straightforward task. The same process for single player would likely to include major code and GUI refactoring, and all for much less obvious benefits than in the case of multiplayer.

[Dugi]

Okay then.

[lipk]

The options WML interface has been changed already, see OptionWML for details. Also commited a fix which makes modifications (and eras, by the way) function properly with mp campaigns (i.e. they're active in each scenario, not just the first one).

All changes will be first included in 1.11.2.

[Gambit]

Here's a screenshot of the options interface in case anyone still has doubts that it is the coolest thing since sliced bread.

[lipk]

Bump. Now we have combo boxes as well. (Will be available in 1.11.8 and onwards.)