Firaxis - Please document the SDK, Python, XML

[Uty]

My company writes medical imaging software. Among our products is a development framework that allows other companies to quickly build their own medical imaging software. So, in a nutshell, we are writing code that other companies/people use to write code.

This is similar conceptually to the SDK (to be released), Python, and XML modification elements included in Civilization IV. I really think you guys did a great job by including this. The mod community did wonderful things with Civilization III and I get the feeling that imagination will be the limit this time around. (I am very excited.) However, I don't feel that you have followed through. These tools are not as powerful and worthwhile without proper documentation.

I have some suggestions (that stem from professional API development) to make your product better. I hope they will be taken into consideration.

- Make a development guide. My company's API has hundreds of objects and enumerations. I know what a lot of them do but what I have to remember is my clients do not. That is why we offer a development guide. It is sixty or so pages and it tells clients how they can use our code to make powerful applications. It has common examples. You might consider giving the following examples: making a new civilization, making a new unit, adding a new resource, configuring a civilization's personality, scenario events, new game screen.

- Look at MSDN. While they're notorious for providing code that does not compile, one has to admit that they offer a lot of documentation for each class used in Windows Development. Instead of listing what functions an object has, they describe the responsibilities and usage of an object. They also describe what the functions do, the arguments, and the return values. Consider how you would have learned Windows programming without information!

- Look at the questions people are asking in this forum. Determine what kinds of questions are the most common. Ignore things like "how do I write Python/XML code" because that is already described dozens of other places. Instead focus on queries such as "what does this function do" and "does anyone know what this series of XML tags are for."

- Hire an intern (or three) and have him/her make a mod. This is an exceptional idea because you have a modder in a structured environment but without all the Firaxian knowledge. You will be able to identify what people can figure out and what people can't figure out based on provided documentation. Hence, you will be able to focus on eliminating all nebulous aspects of modding.

- Release this information with your product. This is a matter of convenience and practicality.

Most of all, thank you for making this great game.

 

[tndp]

- Look at the questions people are asking in this forum. Determine what kinds of questions are the most common. Ignore things like "how do I write Python/XML code" because that is already described dozens of other places. Instead focus on queries such as "what does this function do" and "does anyone know what this series of XML tags are for."

Why, those are the questions I've asked! I agree! Go with the advice of the professional: answer my questions.

For myself, I would rather have a more extensive range of examples, I find them generally more accessible than documentation. The re-implementations in the map generation scripts, for example, are very clarifying. There are a number of functions that can be re-implemented (and that people would want to re-implement) for which the current crop of examples may be insufficient (haven't had time to read all of them, though).

Obviously the examples can never be comprehensive, so we'll need documentation once our understanding has matured - but I'd rather have some nice sexy examples first. If they've written some zany mods in-house, they could just post them, that would probably provide us with enough examples to get going.

I understand if they can't do that, though - IP issues aside (they don't own their own work product) any code ~= a patch, a patch may have to be vetted by the publisher to make sure it doesn't break copy protection, the pointy-haired may become involved somehow - documentation they might be able to just release, in which case, yes, they should do so. But if they could work in about three times as many examples into whatever is included in the (inevitable) that would be awesome - as is the game, awesome. I never expected to actually use the built-in alarm clock in a videogame.

 

[ShroudedMist]

An official SDK is when one should expect a heightened level of documentation. The XML and Python code shipped with the game isn't the SDK that Firaxis is hoping to release in early 2006. They're part of the game and necessary to run CivIV. Firaxis could easily have bundled up the XML files and compiled all the python scripts to prevent us from being able to immediately begin modding.

The python scripts are commented perfectly fine if you ask me. The XML schemas seem fairly straight forward as well. You can't expect them to go provide 5 pages of comments within these files merely to bridge the gap of understanding that exists merely because we haven't seen the SDK itself yet.

Between the WorldBuilder manual, Trip and a bunch of the other knowledgeable modder/staff around here I think we're being given a pretty good level of support right from the get go that is allowing people to pursue pet projects.

 

[Uty]

I think a description of what each function (Python) and what each XML tag does is reasonable. There are good comments in the .Py files themselves, but when you look at the Civ IV Python reference (URL not bookmarked on this box, sorry) it's not easy to figure out what's-what.

I know that there are Firaxians on the board and they're helping people out, answering questions. That's awesome. I think they're eventually going to get tired of answering the same questions over and over, which is where this documentation comes into play. I disagree with you on the point that the C++ side is more important to document than the Python/XML side. Any mechanism that is provided to alter the game is more powerful and effective when described.

 

[Vael]

As time goes by though more and more modders already here will know how to do things, meaning those who actually worked on the game won't need to explain things every time someone asks in the future.

 

[rkyte]

I said this in another thread but I'll repeat it here. What we really need is a wiki (if you don't know what a wiki is, see wikipedia.org) so that there is a community maintained repository for all of the information. Wikis are perfect for documenting this kind of thing.

 

[Dale]

And just like dogs, we beta modders and Firaxians teach the puppies by example.

But honestly, I don't see the massive importance of py and xml documentation. If you want to learn them then look up any million manuals on the net. Sure the world builder is different, but there's a manual for it now (and detailed explanation of all the tags). And if you know py and xml, how to read them, and how to write them, it takes a few seconds to realise what each thing is doing. Otherwise, just create your own stuff in the py files.

I'd prefer they allocated time spent fixing bugs and doing x-packs than documenting languages which are extremely well documented on the net already.

Dale

 

[tndp]

Your manual is great, Dale, but it is not *remotely* comprehensive. It's really more of a scenario editing manual than a modding manual, unless there's more to it than manual.zip.

You're also bashing a strawman - Uty explicitly did not ask them to document either Python or XML. He's asking them to document *their code*. This means, at the very least, full descriptions of all the function prototypes. It is sensible to expect that full documentation will come out with the SDK, okay - but I don't think feedback is a bad thing, and I for one would like to see well written, comprehensive docs (including examples, I expressed my preference earlier) than any particular bells and whistles.

The XML also needs more documentation. The meaning of this is obvious? some of it is obvious, and I've cut the obvious parts out. If it's obvious to you, please, tell me what it means (excerpted from BonusClassInfo in CIV4TerrainSchema.xml):

	<ElementType name="iPlacementOrder" content="textOnly" dt:type="int"/>
	<ElementType name="iConstAppearance" content="textOnly" dt:type="int"/>
	<ElementType name="iMinAreaSize" content="textOnly" dt:type="int"/>
	<ElementType name="iRandApp1" content="textOnly" dt:type="int"/>
	<ElementType name="iRandApp2" content="textOnly" dt:type="int"/>
	<ElementType name="iRandApp3" content="textOnly" dt:type="int"/>
	<ElementType name="iRandApp4" content="textOnly" dt:type="int"/>
	<ElementType name="Rands" content="eltOnly">
		<element type="iRandApp1"/>
		<element type="iRandApp2"/>
		<element type="iRandApp3"/>
		<element type="iRandApp4"/>
	</ElementType>
	<ElementType name="iPlayer" content="textOnly" dt:type="int"/>
	<ElementType name="iTilesPer" content="textOnly" dt:type="int"/>
	<ElementType name="iMinLandPercent" content="textOnly" dt:type="int"/>
	<ElementType name="iUnique" content="textOnly" dt:type="int"/>
	<ElementType name="iGroupRange" content="textOnly" dt:type="int"/>
	<ElementType name="iGroupRand" content="textOnly" dt:type="int"/>
	<ElementType name="bArea" content="textOnly" dt:type="boolean"/>
	<ElementType name="bNormalize" content="textOnly" dt:type="boolean"/>

 

[Uty]

With all due respect to you Dale, I think you misinterpreted my post. I'm not asking for an XML tutorial so much as descriptions of what tags such as iRandApp3, etc are for.

(That's a good example of a series of hard to understand tags, tndp, thanks.)

 

[WildWeazel]

The online API is somewhat helpful, in an obscure, half-finished sort of way. Hopefully it's still in development.
http://civilization4.net/files/modding/PythonAPI/

 

[Dale]

My mistake then (sorry for the mis-interpretation).

There is py doco (at Poly) and there's xml doco on the way still being written.

SDK doco I have no idea about.

Dale

 

[PeteT]

Soren mentioned in a chat that one of the things they'll be working on before the release of game's core source code, is documenting it.