As Aq alluded to above, there is documentation on what Techs should look like:
If there are specific questions about anything in there, email or PM me, and if your question isn't stupid, I'll add it to an FAQ in this post. Remember, the only stupid question is one that makes no sense.
Pseudo-FAQ (I made up these questions):
Q. What can a Tech do as an effect?
A. As stated in the docs, a Tech can have an optional EffectsGroup that gets attached to the capitol planet of the empire that researches it. Currently, the capitol and the homeworld are the same thing, but that may or may not change in future versions. IIRC, Tech effects are intended to be fairly rare; usually, Techs should only unlock other Techs, Buildings, or Ship Components (Ship Components are not in v0.3). This EffectsGroup is active as long as the Tech is known
. So +X to resource meter Y's current value is not
an appropriate Tech effect! If you do this, the current level of Y gets ratcheted up every
turn by +X.
Q. What else can Tech and Building effects do?
A. Not a damn thing! If there's no way to make an EffectsGroup that does what you want it to do from the Conditions and Effects listed in the Wiki, you just can't do what you want to do.
Q. How do meter modifications work?
A. Max meters are "zeroed out" at the beginning of each turn, then recalculated from scratch, accounting for racial bonuses, planetary environment, specials, buildings, etc. So having a Building or a Tech whose Effect is +X to Max Y is fine, even if the Building's or Tech's effects are active for many turns.
Current meters don't work that way at all. They represent the current value of meter Y. Changing Current Y by +X will add X to Y's current value every turn it is active. Effects that affect Current meter values should be used in Events only (Events are not in v0.3).
Q. How should I submit Techs?
A. The right way: XML, baby! Read the documentation on this at the bottom of the Effects Wiki linked at the top of this post. This means that you need to actually read the whole Effects page in order to understand how to write a well-formed XML Tech description. I have created a small app that reads a file with Techs in it, and checks it for errors of formatting, dependency cycles in the Techs, bad relationships between them, etc. You can download it at http://freeorion.sourceforge.net/designer-tools.zip
. If you can't bring yourself to write an XML formatted Tech description, your Tech will probably end up in the digital equivalent of a wastebasket. Note that for multilanguage support purposes, you will need to call your Tech something general in all caps, e.g. "WonderFarm", whose description is "An amazing farm site that magically creates barely-edible food.", in category "Growth" would be, in your XML Tech format:
and the actual text would go for now only in the English language file, as:
An amazing farm site that magically creates barely-edible food.
where some poor bastard will have to translate it into Dutch, Russian, Pig Latin, or whatever, and put it in a new language file for that language.
So don't forget to do this in your XML Tech, putting something like those name and description text lines after your actual Tech XML code.
Which reminds me, use the "[ code ]" tag (without the spaces) to quote the XML and name and description text when submitting your Techs in the forums. It makes them easier to read when they are indented.
Q. What should the type and magnitude of effects be? (Can you tell a programmer made that one up?)
A. + or - and small. Our meters only range from 0 to 100; if we want a deep tech tree, we need to keep the modifiers small, and make sure they grow linearly (+ or -) instead of geometrically (* or /). If we have a +10 modifier effect, we can probably only have ten techs or buildings like that in effect. That's not a very deep tech tree. It's best to keep the effects small, like +1, or +2, or +3 for really big ones. Buildings should be the main sources of effects, not Techs, and Buildings should usually have areas of effect. The bigger the bonus, the smaller the area of effect should be, and vice versa. Large bonuses should also be accompanied by moderate to large penalties in some other area. For example, WonderFarm might give +5 Max Food to all planets within one starlane hop, but also penalize Industry by -3 on those same planets. If its effect were +1, it would be fine to give it a bigger area of effect, and no penalties. This doesn't mean you can't have +50 modifiers, but just that you need to balance them out.
Q. Can I submit a Tech that unlocks a Building without also providing an XML formatted BuildingType definition for the unlocked Building?
A. What do you think?
Q. Can I submit an incomplete XML definition of any kind?
A. I'll give you three guesses.
Q. How the hell do refinements work?
A. I'm glad you asked. Currently, they don't. I'm going to create one or more Effects that edit the definition of a BuildingType, and that should do it. That means that if Application Tech A unlocks WonderFarm, and Refinement Tech A1 improves WonderFarm, the improvement will be to somehow change the definition of WonderFarm so that it works better. This will be extended to Ship Components in v0.4 and later. Since this is still in the works, write your Refinement Techs that improve building performance as completely as you can, and once I have a system worked out you can fully write Refinements.FAQ:
Q. What does the FOCUS_UNKNOWN enum value do?
A. Nothing useful; you shouldn't use it. It is used internally within the code.
Q. If I don't need an activation condition for an effect group, as I always want the effect group to be active, can I omit the activation condition, or should it be included with just <Condition::All/> ?
A. You need to put something. <Condition::All/> will work, but <Condition::Self/> should also work, and will be more efficient.
Q. Under the distance conditions there is a warning:
"Warning: this Condition can slow things down considerably if overused. It is best to use Conditions that yield relatively few matches."
Is this still the correct condition to use when matching objects within the same solar system as the target (ie, set distance to 0, as per the orginal Geoff/drek effects doc)? And will using this condition with distance set to 0 (or 1 for one starlane hop away) liberally slow down execution dramatically?
A. The distances in the WithinDistance and the number of starlane hops in WithinStarlaneJumps is not what slows things down. It's the number of things returned by the Condition inside the Within* Condition that really slows things down. For instance, WithinStarlaneJumps with jumps=5 and condition=Self, which means "Anything within 5 starlane jumps of myself", is going to be a LOT faster to evaluate than WithinStarlaneJumps with jumps=5 and condition=All, which means "Anything within 5 starlane jumps of any other thing." The former must compare all objects to Self, and see how many starlane jumps there are between them, whereas the latter must compare all objects in the universe to each and every other object in the universe, and see how many starlane jumps there are between them. So if there are N objects in the game universe, the former will take time proportional to N, and the second will take time proportional to N squared! Use with caution.
Q. re: the string table. Can we include any formatting (such as HTML) or at very least line breaks? From the example, it appears that a line break indicates a new entry, and there's no quotation marks or markups delimitating the end/start of a string. I'm thinking of the nice descriptions that SMAC had for their techs: if you look at the text files for the descriptions they are nicely formatted via mark-ups.
A. You can insert "\n" anywhere you want a line break. You can also do quite a lot of formatting to the text, but it will be ugly. For basic formatting:
GG::Font supports a few text formatting tags for convenience. These tags are similar to HTML or XML tags; there is an
opening version "<tag>" and a closing version "</tag>" of each tag. It is important to note that GG::Font tags represent
state change, and so cannot be meaningfully nested. For instance, consider the use of the italics tag <i> here:
<i>some text <i>and </i>some more text</i>
In this example, everything is italicized except for "some more text". Each <i> tag establishes that italics should be
used for all further text until the next </i> tag. So the second <i> tag is redundant, as is the second </i> tag. Each
respectively activates or deactivates italics when that is already the current state. The text justification tags are used
on a per-line basis, since it makes no sense to right-justify only a part of a line and center the rest, for instance.
When more than one justification tag appears on a line, the last one is used. A justification close-tag indicates that
a line is to be the last one with that justification, and only applies if that justification is active.
The supported tags are:
- <i></i> Italics
- <u></u> Underline
- <rgba r g b a></rgba> Color. Sets current rendering color to that specified by parameters. Parameters may be either floating point values between 0.0 and 1.0 inclusive, or 8-bit integer values between 0 and 255 inclusive. All parameters must be in one format or the other. The </rgba> tag does not restore the previously set <rgba> color, but instead restores the default color used to render the text. (Example tag: <rgba 0.4 0.5 0.6 0.7>)
- <left></left> Left-justified text.
- <center></center> Centered text.
- <right></right> Right-justified text.
- <pre></pre> Preformatted. Similar to HTML <pre> tag, except this one only causes all tags to be ignored until a subsequent </pre> tag is seen.
For links into Tech and BuildingType encyclopedia entries, just like in the SitRep text:
Where [string] is the name of the Tech, BuildingType, or other Encyclopedia entry (the name from the XML formatted definition, not the language-specific translated name). Currently, there is no Encyclopedia, but as you can see I've built in support for it from the beginning. This will appear as regular text (translated text, not the XML stuff), but will work like a link does in most web browsers: if you roll over it with the mouse, it will appear underlined, and clicking on it will "follow the link", just like in the SitRep.