Mission format

[gajop]

Added etherpad issue: http://etherpad.springrts.com/p/mission_format.

Original proposal:
I'd like to propose a mission format that can be implemented in the engine and used in unitsync and the lobbies. I would also like to point out that this format does not specify an actual "mission runner" implementation. That is left to the mission creator, and from what I understand, we have about 4 mission runner implementations already.

So why do we need this?
Well, missions depend on a specific map and mod and usually don't allow all team combinations, so I don't think it's correct to continue treating them as a regular game.

Firstly, missions should be defined by a new modtype in the modinfo.lua.
[code]
modtype=2,
[/code]
Now regarding maps, there are two ways of dealing with that I guess.
We can either specify them using a separate field, called map:
[code]
map="Delta Siege Dry",
[/code]
or we can specify that in the depend table, along side the game:
[code]
depend = {
"Original Game v2",
"Delta Siege Dry",
}
[/code]
The second option sounds nice since we can reuse the existing mechanism, but I'm not sure if you can have maps in the depend table, and there might be an issue with ordering in the depend table affecting behavior.

Next, regarding teams, we need to specify the following at least for each team
- Name: if unspecified: lobby decides
- AllyTeam: if unspecified: lobby decides
- IsMandatory: defines whether this slot must be filled or not, if unspecified: 0
- IsPlayer: defines if this slot must be used by a Player: if unspecified: 0
- IsAI: defines if this slot must be used by AI: if unspecified: 0
- AI: defines the AI which will play this team, requires IsAI=1: if unspecified: lobby decides (meaning we could potentially allow custom AIs to be used in the mission)
- CanCoop (better name?): defines if multiple players/AIs can play on the same slot (they still must obey the isPlayer or isAI if set), if unspecified: lobby decides
- Side: defines the team's side name, if unspecified: lobby decides

Looking at a map (as they also define team positions), we can reuse the existing format resulting is something like this:
[code]
[TEAM0]
{
Name=Player;
IsPlayer=1;
IsMandatory=1;
AllyTeam=1;
}
[TEAM1]
{
Name=Enemy;
IsAI=1;
AI=NullAI;
IsMandatory=1;
AllyTeam=2;
}
[TEAM2]
{
Name=FriendlyAI;
IsAI=1;
AI=NullAI;
AllyTeam=1;
}
[/code]
I guess this could be placed in a file separate from modinfo.lua, in the case of maps we have those .smd files, so probably something like that.
Obviously we could implement all this in modinfo.lua, let's say we add a table called teams:
[code]
teams = {
{
Name="Player",
IsPlayer=1,
IsMandatory=1,
AllyTeam=1,
}, {
Name="Enemy",
IsAI=1,
AI="NullAI",
IsMandatory=1,
AllyTeam=2,
}, {
Name="FriendlyAI",
IsAI=1,
AI="NullAI",
AllyTeam=2,
}
}
[/code]

Thoughts?

[Silentwings]

What about, instead, when modtype=2 was specified, having the modinfo file also specify a filename for a script.txt file, which could exist inside the missions sdz and (in the already established format) contain data about map, teams, AIs, etc.

Of course it would require a bit of new code to check the dependencies asked for by the script.txt before spring actually tried to run.

[gajop]

What about, instead, when modtype=2 was specified, having the modinfo file also specify a filename for a script.txt file, which could exist inside the missions sdz and (in the already established format) contain data about map, teams, AIs, etc.

Of course it would require a bit of new code to check the dependencies asked for by the script.txt before spring actually tried to run.

Just to be clear (and I guess you agree), the file you are talking about is definitely not your regular startup script ("script.txt"). The lobby-generated startup scripts are concrete instances: besides defining the exact team configuration, they also define additional things, such as host IPs, ports, and similar.
I have used a vocabulary similar to script.txts because it might make it easier to parse them.

It's also OK to separate this from the modinfo.lua (but I don't think we need to specify filename, we could just use missioninfo.lua in all cases).

[FLOZi]

Please don't write tdf in lua syntax, makes my eyes bleed

Code: Select all

teams = {
  {
    Name = "Player",
    IsPlayer = true,
    IsMandatory = true,
    AllyTeam = 1,
  }, 
{
    Name = "Enemy",
    AI = "NullAI", -- implies IsAI = true anyway!
    IsMandatory = true,
    AllyTeam = 2,
  }, 
}

[Silentwings]

Just to be clear (and I guess you agree), the file you are talking about is definitely not your regular startup script ("script.txt")

The ZK mission editor can generate script.txt files (compatible with current Spring) that when given to spring.exe will start a mission with AIs + a player, loaded with a given map and a given sdz to run the mission. Afaik there is no IP/ports involved there; it works offline and I think ZK lobby has a way of implementing it to work online, although I've never tried it myself. So - as far as I can see the current script.txt format is able to do everything necessary for single player missions.

Maybe for multiplayer missions it would break down; I've never tried to do that.

[PepeAmpere]

In NOTA we have working singleplayer and multiplayer scenarios with own specification and standards (more you can see on banned pages and banned NOTA stuff manuals). We have working "separate files" (mod-sceanrio .sdz) missions but in last years we were more supporting "in game" embedded scenarios (mission_name is parameter of standard game file launch), because spring engine upgrades fucks whole thing up. You still need to maintain game + missions together to make it playable and compatible with new engine, so developing it separatelly has no sense until you have dedicated person just for scenarios.

So, thing gajop is suggesting is just for projects with many devs in team. And it will eat powers of engine devs (comminity) to specify thing, which tends to be designed specific way for specific game.

Results:

• for own-driven single-person team developing it brings nothing - such person has no manpower to benefit from this, because engine upgrades (and upgrades of this standard) force him to do another ton of new stuff with every iteration of upgrading
• for big teams (in long term) it can bring small benefit, that standard of mission making is discussed, but because limited resoucres of community/spring devs, this will drain resources which can be invested in basic engine features (optimalization, bug hunt, ...) (preference of PepeAmpere)
• such small benefit goes to hell in case you have specific game design which doesnt fit classic RTS measures, so you still have to develop own standard which satifsfy your needs better.

So I expect developer of new spring game will reuse some working standard of other game (ZK editor, NOTA missions, etc...) or make own one + everytime use own launcher for it.

Mission launching anyway is lobby thing (or own launcher thing) in the end and good new game needs good own lobby (or own launcher). No engine standard and "default lobby enough for all" will satisfy mass user and Im sure it wont satisfy good game dev.

[zwzsg]

The current script.txt, with a little abuse of custom tags, and a gadget inserted in the mod to interpret mission tags, was enough for me to store missions. The most annoying problem was that script.txt filesize is limited. And the workaround I use for that is clunky.

In gajop exemple, I see mostly tags very close to existing script.txt tags, to define the teams and AI. The only differences seem to be the IsMandatory. Instead of redefining a whole new tag forest for a new file, I'd rather have an extension of script.txt.

[PepeAmpere]

I'd rather have an extension of script.txt.

Yes, script file (not perfect, but working solution) is enough and you need only launcher which generate it or use it. When i was talking about launcher/lobby soltion, i had KP launcher in mind, good example how it can look like for developer with limited dev resources.

Sidequestion: where is limit of script.txt specified? I know there is limit for lines lenght,.. is there any limit for size?

[zwzsg]

Sidequestion: where is limit of script.txt specified? I know there is limit for lines lenght,.. is there any limit for size?

I didn't know there is limit for lines. I only know about limit for size, which is 32kB.

It is not specified anywhere. I heard it has to two with arguments sizes in the command interpreter. It depends on the operating system. Check with a real dev for details.

[SinbadEV]

So two parts... first engine side extensions to the existing script format and second some kind of "mission script template" format that lobbies could parse to allow users to start missions?

[zwzsg]

Gajop pretends current script.txt is unadapted to mission for two reasons:

+ They contains host IPs, ports, and similar, which are irrelevant for missions:
Well, my missions uses:

Code: Select all

	OnlyLocal=1;
	HostPort=0;
	IsHost=1;

Note that a value 0 for the port does not force the the port to be 0, but is a special value to tell the engine to choose a port by itself.
For engine up to 0.82.7 I used to have HostIP=localhost; but for latter engine version I have to remove or comment out the HostIP tag.

+ They are too rigid about the exact team configuration:
Personally I doubt you can swap allegiance, change AI, add/remove teams, and still have meaningfull missions. But, as general philosophy, that I don't see myself the point of a feature doesn't mean it's necessarily bad: Opening more possibilities is usually a good thing. But this is still not a reason to throw away the whole script.txt. Making some fields as optional, or adding IsOptional / IsMandatory tags, would make more sense than reinventing a brand new file and syntax.

[gajop]

Thanks for the responses guys :)

The ZK mission editor can generate script.txt files (compatible with current Spring) that when given to spring.exe will start a mission with AIs + a player, loaded with a given map and a given sdz to run the mission. Afaik there is no IP/ports involved there; it works offline and I think ZK lobby has a way of implementing it to work online, although I've never tried it myself. So - as far as I can see the current script.txt format is able to do everything necessary for single player missions.

Just so we're clear, I know it can be done, as I'm also generating script.txt files. It's pretty trivial to do so, but only possible for the fixed team configurations.

Maybe for multiplayer missions it would break down; I've never tried to do that.

Yep, it would break down for these, as well as any other missions in which you would have arbitrary number and type of allies.

We have working "separate files" (mod-sceanrio .sdz) missions but in last years we were more supporting "in game" embedded scenarios (mission_name is parameter of standard game file launch), because spring engine upgrades fucks whole thing up. You still need to maintain game + missions together to make it playable and compatible with new engine, so developing it separatelly has no sense until you have dedicated person just for scenarios.

So, thing gajop is suggesting is just for projects with many devs in team. And it will eat powers of engine devs (comminity) to specify thing, which tends to be designed specific way for specific game.

I don't see how saying "Spring engine upgrades fucking the whole thing up" implies that you shouldn't separate missions from games, or that it takes additional dev power to do this, please elaborate.

The system I'm suggesting would produce a similar result to how it's done currently, with the added benefit that it would be easier for lobbies to integrate (run) missions, especially so for multiplayer ones (and multiplayer is the hearth of this community).

Mission launching anyway is lobby thing (or own launcher thing) in the end and good new game needs good own lobby (or own launcher).

This is at the core of my proposal. It will make things easier for the lobby dev, as they won't need to parse 4-5(?) different mission formats, but can instead rely on an existing one, which in turn means its easier to provide a good interface to the players. Imagine how things would look like if we had 5 game formats (modinfo in different formats).

The current script.txt, with a little abuse of custom tags, and a gadget inserted in the mod to interpret mission tags, was enough for me to store missions.

To repeat myself yet again, yes, script.txt can work in the most trivial case for missions: a case when you have fixed team configurations.

In gajop exemple, I see mostly tags very close to existing script.txt tags, to define the teams and AI. The only differences seem to be the IsMandatory. Instead of redefining a whole new tag forest for a new file, I'd rather have an extension of script.txt.

Tags are "very close" by design. It allows us to reuse code and people are already familiar with the script.txt tags.
However you shouldn't ignore one key difference, and that's the fact that this file should not be used to start a game directly, but rather as a template from which an actual script.txt would be generated. This means you can have arbitrary amount of teams, with arbitrary allyTeams, played by players or AIs, etc. You just can't have that with your plain script.txt (that's really a concrete game then).

Gajop pretends current script.txt is unadapted to mission for two reasons:

+ They contains host IPs, ports, and similar, which are irrelevant for missions:
Well, my missions uses:

Code: Select all

	OnlyLocal=1;
	HostPort=0;
	IsHost=1;

Note that a value 0 for the port does not force the the port to be 0, but is a special value to tell the engine to choose a port by itself.
For engine up to 0.82.7 I used to have HostIP=localhost; but for latter engine version I have to remove or comment out the HostIP tag.

How will this work in multiplayer?

+ They are too rigid about the exact team configuration:
Personally I doubt you can swap allegiance, change AI, add/remove teams, and still have meaningfull missions.

Yes you can. I actually don't play many different RTS games but here are two examples:
1. Every Red Alert 3 campaign mission can be played in a 2-player co-op or alternatively alone with a friendly AI.
2. Nearly every Warcraft 3 (game that can rightfully be called 'the king of missions') scenario allows an arbitrary team configuration. While not every one allows arbitrary allyTeams (some might?), in many you can have arbitrary teams. For example, it was not uncommon to see Footman frenzy be played in 3v3, 4v4, 3v3v3, 2v2v2v2, 4v4v4v4, etc.

But this is still not a reason to throw away the whole script.txt. Making some fields as optional, or adding IsOptional / IsMandatory tags, would make more sense than reinventing a brand new file and syntax.

Obviously I'm not "throwing away the whole script.txt". I'm suggesting something that's pretty darn similar to script.txt and will later be used to generate those script.txts. Oh and btw, something like that already exists, just check those map .smd files. Well, what I think we should have is something similar to that, but geared towards missions.

but because limited resoucres of community/spring devs, this will drain resources which can be invested in basic engine features (optimalization, bug hunt, ...) (preference of PepeAmpere)

It's entirely up to the devs themselves how they plan to spend their time, but if it turns out "they" don't have the time then I will implement it myself (as its a preference of gajop). The issue isn't in the implementation (it's a fairly simple format, similar to what we have already). What we need to do is communicate it well before it's done, so we can get to a format we can agree on.

To summarize:
Multiplayer matters, Co-op matters. Just producing script.txts is a needless oversimplification. We aren't doing it for maps, and we shouldn't do it for missions either.

[Silentwings]

Ok, I understand why you want to do this now. This is a good idea, please implement it!

I would personally favour a missioninfo.lua file that sat next to the modinfo.lua file and was only used by the lobby/engine if modtype=2 was found in modinfo.lua.

It would be great if this could work with Spring.Restart somehow, allowing for multi-stage multi-player missions.

[PepeAmpere]

Ok gajop, some of your arguments are valid (mentioned below), but:

• "mission/scenario" (term) definition is much more complicated then definition of "map" or "game". Designing mission handling for general use is making new programming language (not simple one), its not few lines thing. I think you (gajop) know it and starting such discussion in such way you did not provide me much optimism in result. (+ Sorry, i don't want to let desing this thing by person, who said, that doesnt play much other RTS games. I dont consider myself enough good for designing such thing for general use, for all games, but at least i think i have detail experience with tens of RTS games, which i consider necessary for designing it and I have one successfull atempt of making it.)
• If you add such standard (which is prefered against all others, official one), you force all users of engine to somehow face it, if some parts will be mandatory, you force all other systems to specificaly overwrite this general standard. I dont believe it will be something, which would be totaly optional, which i can ignore if not interested. (this is why i care about "addition work" with every engine upgrade)
• You try to specify something, which has huge implications in other areas - like synchronization, downloading system, updates, versioning, launch standards. Another thema, which was not mentioned at opening post.

Ok, some constructive part now:

I would prefere some comparation report of previous solutions first OR finished design doc of new system instead of such at forum created and developed idea. Your way of online creating cost me, as interested dev, much more time, because i have to check few times a day this thread (and many others) just to prevent bad decisions, which can (one day) affect my project bad. Facing "just ideas" is exhusting, too.

If you like to design new system from scratch, so , please, prepare "mission standard" specification (real document, with no "should", "could", "may", "maybe"), give us space to comment it, and we can make 3-5 such iterations to move it in acceptable solution.

Summary

As I said, mission handling is lobby/launcher thing, so its lobby dev OR own game launcher designer matter somehow solve this. Lobbies able to understand own kind of standard were developed (ZKlobby, notAlobby), their system works (if you want multiplayer), own game launcher (for Kernel Panic) is able to launch game mission, too, (if you want simple single).

If anyone needs it for own game, he can use some open standards developed yet or invent own one.

If you plan to invent new one, which is forced to others via "its official, dude", dont call it "mission format", but "mission format for spring lobby" to be clear and honest. I would prefere free competition of mission making standards until I see your idea is way much better then any made before. It is not, yet.

[gajop]

The first part is just filled with bad arguments, so instead of a detailed response I'll just give this:
- Playing "tens of RTS games" is a joke, I have easily played a hundred RTS games over 20ish years I have been gaming (while still not playing some of the better ones like Company of Heroes or newer Warhammer 40k), and that still amounts to no more than 5/year, which isn't that much. But more importantly it's the developers that make games, not gamers. I have been designing my scenario editor on and off for more than a year, so I am more than capable of understanding the requirements of a mission format..
- No one is forcing you to use this. There's nothing in place that would undermine the existing system and I don't plan to introduce it.

I would prefere some comparation report of previous solutions first OR finished design doc of new system instead of such at forum created and developed idea. Your way of online creating cost me, as interested dev, much more time, because i have to check few times a day this thread (and many others) just to prevent bad decisions, which can (one day) affect my project bad. Facing "just ideas" is exhusting, too.

If you like to design new system from scratch, so , please, prepare "mission standard" specification (real document, with no "should", "could", "may", "maybe"), give us space to comment it, and we can make 3-5 such iterations to move it in acceptable solution.

Forums are for discussing things - ideas included. I have provided a detailed draft here and plan to use the discussion here to finalize it in a specification. I don't know what you would consider not being "just an idea", should I have implemented the whole thing first before presenting it to you..? This is not something that will be done over night, so rest assured, you don't need to "check it a few times a day".

As I said, mission handling is lobby/launcher thing, so its lobby dev OR own game launcher designer matter somehow solve this. Lobbies able to understand own kind of standard were developed (ZKlobby, notAlobby), their system works (if you want multiplayer), own game launcher (for Kernel Panic) is able to launch game mission, too, (if you want simple single).

How do they deal with non-fixed team configurations (in MP), that is, how do they force valid team configurations?
Again, just creating script.txt files for fixed-team SP is trivial, I've shown my link to it. Allowing any team-config for MP is also pretty easy, but quite limiting.

If anyone needs it for own game, he can use some open standards developed yet or invent own one.

If you plan to invent new one, which is forced to others via "its official, dude", dont call it "mission format", but "mission format for spring lobby" to be clear and honest. I would prefere free competition of mission making standards until I see your idea is way much better then any made before. It is not, yet.

For some reason you are confusing an "implementation" with an "open standard", because none of these things are _standardized_. Not to mention that their standard isn't "open". There is no specification of the format either.
Also if by "spring lobby" you mean the lobby called "SpringLobby", then no, I haven't mentioned SL yet in this thread. I don't develop for SL nor have any particular favoritism towards it. I have in fact started a development on Chili lobby so that statement is just invalid.
If OTOH you mean lobby support for Spring, then yes, this is meant to benefit the lobbies mostly, as they'll have a well-defined format they can use with all mission runner implementations.

[PepeAmpere]

Ok.

[abma]

+1 for a mission standard as it allows:
- listing on game sites
- can be used from all lobbies
- engine support could be added as well

currently every lobby/game has its own format, this makes it difficult to support in other parts of our infrastructure.

i'm not sure if the required basic info can be added/changed in modinfo.lua or of a file like missioninfo.lua has to be used.

using modinfo.lua:
overrrides the file provided by a game if the existing depends are used

using missioninfo.lua:
needs additional code to parse in unitsync / lobbies to download depends

[zwzsg]

modinfo.lua? I fail to see how it is related to missions.

I'd still say script.txt are closest to what missions needs, not to say, all that missions need.

If a standard has to be defined for engine and lobbies, I would say:
- Every *.txt files in the folder /Missions/ (including subfolders), inside a game archive, shall be considered as a startscript that runs a mission.
Yeah, KP is already compatible to that standard.

[abma]

- Every *.txt files in the folder /Missions/ (including subfolders), inside a game archive, shall be considered as a startscript that runs a mission.

imo missing:
- file dependencies
- team info to allow coop-games, etc
- some description/name of the mission

dedicated file(s)/folder(s) for missions seems reasonable as it would allow mutators. not sure if a file structure like this makes sense (inside an archive):

missions/missionA/missioninfo.lua
missions/missionB/missioninfo.lua
...

this way multiple missions can be in one archive and it can be inside a game or a dedicated file as well.
not sure how to tag an archive as mission archive, a tag inside modinfo.lua is maybe enough?!

[gajop]

dedicated file(s)/folder(s) for missions seems reasonable as it would allow mutators. not sure if a file structure like this makes sense (inside an archive):

missions/missionA/missioninfo.lua
missions/missionB/missioninfo.lua
...

Having a dedicated folder for missions (much like we have for games and maps) is a good thing, but I don't see why we would have multiple missions in a single archive? Not sure what you mean about mutators either :/