GUI Scripting interface / game setup

[historic_bruno]

Hi, I'm new here, so first let me say I'm quite excited about this project, as one of my friends and I simply love playing AoK together. I'm a computer engineer who enjoys hacking around, experimenting with new ideas, and making things work.

Now, I've delved head-first into the code base, and can see already the importance of scripts in the functioning of the game. It's a great idea. I would like to contribute, and so have selected something simple to play with (or so I thought), which is to modify the game setup a bit.

Modifying the GUI layout is trivial (though admittedly would be easier with an editor). I've added a column to choose "civilization" for the players. The problem of course, is when I want to write the script to hook these GUI objects up to the engine. It seems there is a lot hard-coded into the scripts (both setup and map generation) simply to get them to run with a human and some other dummy players, which is fine since it's an alpha. I discovered there's much missing from the scripting interface and it seems in need of some serious thought more than hacking up a bit of additional behavior.

I'm also not keen on making changes like this without first finding out who's responsible for it now, and also if there's active work on it. Would be interesting to bounce some ideas around, maybe in this thread.

Hope to hear back from some of you,

historic_bruno

[Ykkrosh]

Welcome

The problem with changing civs is that it doesn't really make sense for static maps - they're created in the map editor with specific buildings and units for each player, and there isn't a 1:1 mapping onto equivalent units for different civs so we can't easily change them automatically, and in some cases they'll be history-based scenarios so changing the civs would be illogical. It'd work much better with random map scripts, since they can programmatically construct whatever starting units are suitable for each player based on their civ selection and other parameters, but we don't currently have a working RMS system . The current vague plan is to try to get RMS running properly some time soon (i.e. within the next several months, when someone has time to do it) and then have it integrated with the GUI for civ selection. Nobody's currently working on any of that, though.

[WhiteTreePaladin]

Hi historic_bruno,

I'm working on the ingame GUI layout (resource bars, unit icons, etc.) Most of what I do there is aesthetic. We would be glad to have help with any area you're interested in.

By the way, random map scripting did work in the old simulation, but it hasn't been ported over to the new simulation system. That's why it's broken.

[Jeru]

Hi historic_bruno, I just wanted to say welcome and ask how you heard about 0 A.D.

[Ykkrosh]

By the way, random map scripting did work in the old simulation, but it hasn't been ported over to the new simulation system. That's why it's broken.

Actually that's not quite why - the rmgen tool is an external executable that creates .pmp/.xml files in a slightly old format, and the engine should still be compatible with that old map format. The problem is mainly that it's an external executable, which makes it a pain to build and to integrate with the game engine. Also it's got a lot of C++ code exposed to scripts, which is not great for flexibility or for security (I doubt it's impossible to crash, and it'd be nice for RMSs to be perfectly safe to download). I think the best approach would be to rewrite most of it, putting a minimal layer in the game engine and then porting all the interesting functionality (the algorithms for terrain generation and object placement etc) to pure JS. (JS is fast nowadays, and SpiderMonkey provides typed arrays that can efficiently represent terrain heightmaps, and we could probably do nice stuff like provide a browser-based development/debugging environment for RMS.)

[WhiteTreePaladin]

Ah, thanks for the correction, Philip.

[historic_bruno]

Thanks for the quick responses, obviously a very active project here

The problem with changing civs is that it doesn't really make sense for static maps - they're created in the map editor with specific buildings and units for each player

OK, that makes sense. Ideally then the setup GUI would be populated with data for a static map (ie. the number of players, names for historical purposes, civs, map size, etc). Or it would have ways to choose that data in the case of a random map.

Looking at existing scenarios, there is a PMP which I assume is some kind of binary data for defining map/terrain. Then there's XML which seems to specify units and a few settings. Could player civilization, name, map size, etc, be defined in that XML, perhaps in a new PlayerSettings element?

I haven't looked into the old random map generator, but given the rest of the project it would make sense to be in JS along with the RMSs. There's a lot to think about there, no wonder it hasn't been started

I'm working on the ingame GUI layout (resource bars, unit icons, etc.) Most of what I do there is aesthetic. We would be glad to have help with any area you're interested in.

OK, I have some ideas from testing the software. Maybe I can get my friend involved as well, he's new to scripting but learning fast, and good with aesthetics too

Hi historic_bruno, I just wanted to say welcome and ask how you heard about 0 A.D.

Thanks, Jeru. I found 0 A.D. when I was looking for open source games on Wikipedia, specifically RTS games because though I enjoy AoK, I also get frustrated by it's limitations. I had no idea this project existed until a few days ago. It makes a huge impression though, seeing the professional graphics which are far beyond almost any other open source project

[WhiteTreePaladin]

though I enjoy AoK, I also get frustrated by it's limitations.

That's the story of more than a few members here...

[Jeru]

Thanks, Jeru. I found 0 A.D. when I was looking for open source games on Wikipedia, specifically RTS games because though I enjoy AoK, I also get frustrated by it's limitations. I had no idea this project existed until a few days ago. It makes a huge impression though, seeing the professional graphics which are far beyond almost any other open source project

Thank you for the answer and the compliments, they are much appreciated.

[Ykkrosh]

Looking at existing scenarios, there is a PMP which I assume is some kind of binary data for defining map/terrain. Then there's XML which seems to specify units and a few settings. Could player civilization, name, map size, etc, be defined in that XML, perhaps in a new PlayerSettings element?

Yep, the PMP is the terrain heightmap and texture data, the XML is everything else. For map data that is just used by GUI scripts or simulation scripts (and eventually by the map editor too), the XML file contains JSON data in a <scriptSettings> element, so it should be straightforward to add player data into there.

[historic_bruno]

I've had a go at this, and here's what I've come up with.

For the scenario XML files, I've inserted player data into the ScriptSettings element as follows:

Revised: 10-25-2010
...
	<scriptSettings><![CDATA[
	{
		"Name":"Scenario name goes here (optional)",
		"Description":"Scenario description goes here (optional)",
		"Keywords":["keyword_1", "keyword_2", "keyword_n"] (optional),
		"PlayerData":
		[
			{
				"Name":"Player name (optional)",
				"Civ":"hele/celt/iber/pers/cart/rome (optional)",
				"Colour": { "r": 0-255, "g": 0-255, "b": 0-255} (optional),
				"PopulationLimit": 0 (optional),
				"Resources": {"food": 1000,	"wood": 1000,	"metal": 500,	"stone": 1000} (optional),
				"Team": -1 for no team or 0-4 (optional),
				"Diplomacy": [] array of diplomatic stances between players (optional),
				"Phase": starting phase (optional - not implemented?)
			}
			...
		],
		"GameType":"endless/conquest (optional)",
		"RevealMap":true/false (optional),
		"LockTeams":true/false (optional - not implemented yet),
		"DefaultStance":"holdfire (optional)"
	}
	]]></ScriptSettings>
...

As you can see I added some player data that would come from Atlas. For example, starting resources could differ based on the player, as could population limit, and various other attributes. Some of these may be optional, in which case a default would be specified in the game setup script.

I also added a name property for the map itself, which allows special characters beyond what the filename supports.

On the GUI side of things, I've added a dropdown for selecting map type (random / scenario). The available map list is updated based on this selection. Random really has no point yet as there's no implementation. You'll notice the "civilization" column. For scenarios it is disabled and only for display purposes, for a random map it will be a full list of civs. Since number of players is specified in the scenario, I've hidden extra player slots.

Would love to hear comments, criticisms, etc.

Here's a screenshot:

Edited December 5, 2010 by historic_bruno

[Shield Bearer]

interesting. i don't know much abt the programming side of this but i like the progress

[historic_bruno]

Some open tickets related to this topic:

#1: Player Properties

#316: GUI - Civ Selection Dialog

#527: Display correct player names

I didn't see #316 before, any progress on this? The related thread hasn't been updated in a year. Some interesting ideas there, but no patches or scripts yet... I'll assume since the SVN has none of those changes at all (see my screenshot) that progress on that has stalled somewhat.

Some related thoughts.

1. There's at least 4 cases of game setup: multiplayer(networked) scenario, single player scenario, multiplayer random, single player random.

The code for these is currently in a single script, which is getting ugly as logic is added to handle each of the above cases. For example in random mode a GUI object might mean something different from the same object in scenario mode, while in multiplayer mode there is a need to keep players synced as settings change, but this is not the case in single player mode.

My instinct is telling me that some code shared among all game setup cases should be in one script, and then case specific code should be in other scripts. This could facilitate the future addition of other setup cases, whatever those might be. At any rate it may make it easier to read and write code.

2. It's not clear to me yet, how civilizations are implemented. Obviously there are art, technologies, game data, and rule sets which all have to be unified around this concept of a civilization. In keeping with the modular and generic nature of the underlying engine, I guess scripts will be responsible for tying this together. Where can a script, for example game setup, find a list of available civs? For loading maps, it reads a directory for all files matching a given extension. Maybe the same could be done for civs, if I find the "primary" location for that data.

Perhaps an XML for each civ, with properties such as internal name, display name, history, and whatever other data could be useful for GUI display.

3. GUI controls really need to be more informative to the user. The state should always be apparent, if it's disabled, it should look disabled. If an item is selected, it should instantly be clear what is selected and what is not. I'm thinking that I saw a ticket for this, but now I can't find it

4. Maps and really any modular data should be checked before use, to verify they are compatible and at least syntactically correct. If you make a syntax error in your script while the game is running, it can potentially lock up the game (this has happened to me). While it's nice to see changes appear instantly, it needs to be safe

Edited September 25, 2010 by historic_bruno

[historic_bruno]

The detailed civilization info absolutely needs to be in its own dialog, something like the mockup Jeru posted here. In AoK, this data is presented as a technology tree with brief history. There could be a "?" button next to the civ dropdowns, which instantly jumps to the corresponding info dialog? Or something a bit less minimalistic.

How about a repository for civ data in /mods/public/civs? The XMLs could go there.

Another ticket:

#91: Player editor for Atlas

- This would modify the map XML to include something like the PlayerData element shown above.

Edited September 25, 2010 by historic_bruno

[Ykkrosh]

That XML format could probably be simplified a bit: remove "NumPlayers" (it can be derived from the list of players), remove "ID" (it can come from the index in the Players array), remove Colour.a (it always has to be 1), remove Gaia (it always has to be player 0 so making it explicit in the XML is unnecessary and adds potential for errors). Otherwise it looks good to me.

I didn't see #316 before, any progress on this?

I don't believe so - there were just the design ideas linked from there, and not much more that I can remember. I reimplemented the game setup screen about 4 months ago (since the old one was overly complex and didn't work with changes to the networking system) but I just tried to do a simple barely-sufficient design, rather than basing it on the more complex concepts that have been suggested. It hasn't been changed much since then and nobody else is currently working on it, but it could do with some improvements

There's at least 4 cases of game setup: multiplayer(networked) scenario, single player scenario, multiplayer random, single player random.

Also there's multiplayer host vs multiplayer client, which might (or might not) make a similarly-significant difference. (Clients should be able to select their own civ, and we probably want to let them select teams/alliances too, but most other settings can only be edited by the host.)

My instinct is telling me that some code shared among all game setup cases should be in one script, and then case specific code should be in other scripts.

Splitting .js files is easy (just reference them all from the .xml), and modularity is good. Probably the XML layouts are harder - you can't mix-and-match different XML fragments (at least without adding that feature to the GUI engine), so sharing code isn't possible, and duplicating code is bad, but mixing all the different modes into one file is also bad. I'm not really sure what's the least bad approach

Where can a script, for example game setup, find a list of available civs?

Currently, nowhere. Would be a good thing to add - I don't know exactly what data we need, but it probably includes some for the game-setup GUI (name, history, logo, etc), some for session GUI (name, etc), some for random map scripts (listing which entities to place at the start of the game, etc), and some for simulation (toggling civ-specific behaviours, etc). Hopefully there's not too much in total - creating an XML file per civ sounds sensible, and all the different bits of code can read what they need. Probably should go in mods/public/simulation/data/civs/or similar (since it affects the simulation code, not just the GUI).

(One thing we want to do well is supporting mods, and if creating a new civ is as simple as copying-and-pasting an XML file and then editing some of the names, that'd be great )

If you make a syntax error in your script while the game is running, it can potentially lock up the game (this has happened to me)

Hmm, yeah, the hotloading thing isn't entirely robust with invalid input. It seems hard to fix since there's lots of different error conditions all over the place . If one is encountered frequently then I think it's worth trying to handle it more gracefully.

[historic_bruno]

Parts of the engine relevant to player data:

* Atlas - will need GUI controls for player setup: number of players, names, civs, starting resources, etc. Then properly write these to map XML.

* MapReader - will need to load player data from the map XML and parse into entities. also loads summary of map data for setup purposes

* PlayerManager - maintains list of player entities

* ScriptFunctions - interface for GUI scripts to interact with engine, ie. loading map data

* GameSetup - besides GUI changes, will need to properly load map data

Parts of the engine relevant to civ data:

* Atlas - needs to read civ data for display, possibly to select available units?

* CivReader - needed to parse civ XMLs, could be modeled on MapReader? probably belongs in simulation layer

* ScriptFunctions - provide interface for loading civ data?

* GameSetup - needs to read list of civs from file structure(?), show civ info

* CivInfo - parse civ data, and display formatted info on GUI

[historic_bruno]

That XML format could probably be simplified a bit

I noticed this too after thinking about it. Some simplifications will break existing scenarios, but since it's still alpha this shouldn't be a great concern. I'll just update the scenarios I have to be compatible.

(One thing we want to do well is supporting mods, and if creating a new civ is as simple as copying-and-pasting an XML file and then editing some of the names, that'd be great )

My thoughts exactly. I'm working on a structure for the civ XML, using comments here and info from the design document.

I noticed there are sometimes multiple "child" civs for a single parent: the Poleis and Macedonians both under the Hellenes. For this I created the concept of Locales, which are added to their parent civ, and contain specific heroes, technologies, and anything else that could vary by location in the context of a civ.

Eventually there will need to be a standard way of referring to all the gritty details of a civ (special behaviors and units) in a programmatic fashion, I'm not sure that this XML is the correct place to address those details so I've left them in plain English if at all. Maybe that's better suited to the concept of "technologies."

Below is an example XML for the Hellenic civilization, with extraneous data removed:

<Civilization>
	<InternalName>hele</InternalName>
	<DisplayName>Hellenes</DisplayName>
	<Emblem image="hele.dds"/>
	<History>
		<TimeLine/>
		<Text>
			The Hellenes were a people famous for their architecture, fighting ability, and culture...
		</Text>
	</History>
	<Locales>
		<Locale>
			<Name>Poleis</Name>
			<Description>Greek city-states</Description>
			<SpecialTechnologies>
				<Technology>
					<Name>Othismos</Name>
					<History>
						...
					</History>
					<Effect>The player gains the ability to order his troops into a PHALANX formation, providing +30% Attack and +30% Pierce Armour if attacked from the front.</Effect>
				</Technology>
				...
			</SpecialTechnologies>
			<Heroes>
				<Hero>
					<Name>Themistokles</Name>
					<Class/>
					<Armament/>
					<Emblem/>
					<History>
						...
					</History>
				</Hero>
				...
			</Heroes>
		</Locale>
		...
	</Locales>
	<CivBonuses>
		<CivBonus>
			<Name>Oikoumene</Name>
			<History>
				...
			</History>
			<Effect>10-15% cheaper technologies.</Effect>
		</CivBonus>
		...
	</CivBonuses>
	<TeamBonuses>
		<TeamBonus>
			<Name>Oracle at Delphi</Name>
			<History>
				...
			</History>
			<Effect>All units and allied units have increased LOS. ~ 10%</Effect>
		</TeamBonus>
	</TeamBonuses>
	<SpecialStructures>
		<Structure>
			<Name>Theatron</Name>
			<Class/>
			<Emblem/>
			<History>
				...
			</History>
			<Requirements/>
			<Phase/>
			<Special/>
		</Structure>
		...
	</SpecialStructures>
</Civilization>

[historic_bruno]

Update: teams and player colors shown in setup, player civ is text-only in a scenario (dropdown otherwise)

The "?" button at the top, next to Civilization opens up the "Civilization Info" box, which is something like Jeru's mockup only I've got no data for it yet and it's lacking the nice images. Using formatted text, it should be possible to get something close to the mockup, only I've no idea how tooltips or info boxes could be added dynamically for civ bonuses, heroes, etc. But I like that idea.

If there's not already there should be a simple way for a script to set multiple properties of a GUI control at the same time, in an array or something.

Edited September 27, 2010 by historic_bruno

[Ykkrosh]

* MapReader - will need to load player data from the map XML and parse into entities. also loads summary of map data for setup purposes

I think it's best for this to go in gameplay scripts instead of in CMapReader, so that the engine doesn't depend on any details of player data (it just cares about player IDs and otherwise is flexible). (simulation/helpers/Setup.js can set up the player entities based on the map data, probably.) (My current theory is that code only ought to go into the engine when it'd be either impossible or slow or otherwise painful as scripts.)

* CivReader - needed to parse civ XMLs, could be modeled on MapReader? probably belongs in simulation layer

I think this doesn't need to be in the engine, it can just be in scripts. Probably we need to add a way for GUI and simulation scripts to load arbitrary XML (or JSON?) files but then the scripts can do their things without needing more C++.

Some simplifications will break existing scenarios, but since it's still alpha this shouldn't be a great concern.

Yeah, breaking things is fine as long as we update all the maps in SVN, there's no guarantee of stability yet.

I noticed there are sometimes multiple "child" civs for a single parent: the Poleis and Macedonians both under the Hellenes.

Hmm, I'm not quite sure how that's meant to work in terms of the game design - are these separate civs that players can choose from, or are they just historical notes on the unit types that are provided? (Is some designery person reading this?)

Eventually there will need to be a standard way of referring to all the gritty details of a civ (special behaviors and units) in a programmatic fashion, I'm not sure that this XML is the correct place to address those details so I've left them in plain English if at all. Maybe that's better suited to the concept of "technologies."

I'd expect most of the details for technologies and behaviours etc to be specified in independent files, and just referenced by name from the civ data, so they can be easily shared by multiple civs and independently edited by mods. Some of it (e.g. lists of structures) maybe doesn't need to be explicitly specified at all, it's just an implicit consequence of the building/training/etc lists specified in that civ's entity templates.

If there's not already there should be a simple way for a script to set multiple properties of a GUI control at the same time, in an array or something.

Why? (Setting them individually doesn't sound like it'd be a huge pain, but maybe I'm missing the problem.)

Update: teams and player colors shown in setup, player civ is text-only in a scenario (dropdown otherwise)

Looks good to me

[Mythos_Ruler]

Hmm, I'm not quite sure how that's meant to work in terms of the game design - are these separate civs that players can choose from, or are they just historical notes on the unit types that are provided? (Is some designery person reading this?)

The sub-factions are meant to be chosen by the player upon advancing to City stage. When clicking the "Phase III" icon/technology the player is given a choice (I assume with a pop-up dialogue) between the sub-factions. A sub-faction gives you access to Super Units, Heroes, and Technologies specific to that sub-faction. This is similar to choosing 'Minor Gods' in Age of Mythology.

[historic_bruno]

I think this doesn't need to be in the engine, it can just be in scripts. Probably we need to add a way for GUI and simulation scripts to load arbitrary XML (or JSON?) files but then the scripts can do their things without needing more C++.

That actually make things much easier. I was wondering how to load the JSON data into C++ data structures which gets ugly fairly quickly. There's just traces of code that look important but don't serve a purpose anymore. If you look at how things are implemented, map settings are stored as JSON data in the simulator but only used to read and write maps.

Instead all the game data could be in scripts. An XML -> JSON converter would do the trick. And I wonder if there's a reason for the player data to be defined in JSON... why not all XML?

The sub-factions are meant to be chosen by the player upon advancing to City stage. When clicking the "Phase III" icon/technology the player is given a choice (I assume with a pop-up dialogue) between the sub-factions. A sub-faction gives you access to Super Units, Heroes, and Technologies specific to that sub-faction. This is similar to choosing 'Minor Gods' in Age of Mythology.

Thanks for the clarification. Factions is a much better word for them than locales

[Ykkrosh]

There's just traces of code that look important but don't serve a purpose anymore.

Yeah, there's some of that throughout the engine . Good to clean it up when possible.

Instead all the game data could be in scripts. An XML -> JSON converter would do the trick. And I wonder if there's a reason for the player data to be defined in JSON... why not all XML?

The mapping from JSON to an in-memory JS value is trivial; the mapping from XML is more complex and the result is often worse (since e.g. there's no single obvious way to represent arrays in XML) and we'd probably have to write the code ourselves to do it. So it's just easier and more natural to use JSON, when the data's only going to be used by scripts.

[plumo]

About the scenario / 'random map' interface. It wouldnt be bad to have an 'advanced options' button.

F.e. If you want to give a computer opponent a different AI file, to make up for different and challenging playstyles. These can be made by people, like in AOE 2.

[historic_bruno]

OK, it took me a while but I've got player data fully loaded from setup. The best part is: it's all initialized by simulator scripts I'll test some more things and make sure there's no other traces of engine code that modify player data. At first glance it looks good.

The ease of manipulating JSON data in scripts makes me think much or all of the civ data should also be in JSON. Inside an XML document seems to work well for those things that *might* be engine specific (since we have a quite capable XML parser). I'll write one up and see how it looks.

About the scenario / 'random map' interface. It wouldnt be bad to have an 'advanced options' button.

Agreed. Anything that is likely to be set each game should be in plain view, while less common options could certainly be in an "advanced" panel.

Edited September 28, 2010 by historic_bruno

[historic_bruno]

#7: Diplomacy

- Whatever diplomacy variables were added have likely been lost by now.

- Can be supported by adding a "diplomacy" array to each player's data. Numerically, -1 could be enemy, 0 could be neutral/undefined, and 1 friend. Or strings could be used just as easily.

- Requires GUI controls and modification of player class (...simulation/components/Player.js), and of course the game logic to use it