Please read the design/effects document!

Creation, discussion, and balancing of game content such as techs, buildings, ship parts.

Moderators: Oberlus, Committer

Message
Author
Aquitaine
Lead Designer Emeritus
Posts: 761
Joined: Thu Jun 26, 2003 1:54 pm
Location: Austin, TX

Please read the design/effects document!

#1 Post by Aquitaine »

It's quite apparent to me that a lot of people working on these threads have simply not read the design document and/or the effects document.

I should have been more clear about this, but I simply assumed that anybody who was taking part in the design of the tech tree would familiarize themselves with the structure of the tech tree that we spent weeks and months discussing. This was an error on my part.

There are several posts suggesting ways to completely rework the tech tree, techs without pre-requisites, techs without costs and times, et cetera.

This is not a brainstorming thread. If you aren't familiar with how things work, don't waste our time. There's plenty of reading for you that we went to a lot of trouble to write. The design team has to convert all of the techs into XML that fits exactly into the effects document model, so if your suggestion doesn't -- even a little bit -- it doesn't belong here right now. (the effects docucment, of course, will evolve later, and so will the tech tree.)

tzlaine is going to post some additional guidelines to think about. I do apologize for the heavy-handed notice (especially as it's my fault for just saying 'go!' and thinking everybody would have read this stuff) but this is a professional project. Please do us the courtesy of learning how it works.

Aquitaine

p.s. If you have comments about the guidelines, feel free to post them here. If you want to say 'wah Aquitaine is a total jerk,' you can email me.
Surprise and Terror! I am greeted by the smooth and hostile face of our old enemy, the Hootmans! No... the Huge-glands, no, I remember, the Hunams!

tzlaine
Programming Lead Emeritus
Posts: 1092
Joined: Thu Jun 26, 2003 1:33 pm

#2 Post by tzlaine »

As Aq alluded to above, there is documentation on what Techs should look like:
http://www.freeorion.org/wiki/index.php?title=Effects

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:

Code: Select all

<Tech>
    <name>WONDER_FARM</name>
    <description>WONDER_FARM_DESCRIPTION</description>
    <category>GROWTH_CATEGORY</category>
    ...
</Tech>
and the actual text would go for now only in the English language file, as:

Code: Select all

WONDER_FARM
WonderFarm
WONDER_FARM_DESCRIPTION
An amazing farm site that magically creates barely-edible food.
GROWTH_CATEGORY
Growth
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:

Code: Select all

      <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:

Code: Select all

    - <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:

<tech [string]>
<building [string]>
<encyclopedia [string]>
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.
Last edited by tzlaine on Sat Jan 15, 2005 4:20 am, edited 8 times in total.

Aquitaine
Lead Designer Emeritus
Posts: 761
Joined: Thu Jun 26, 2003 1:54 pm
Location: Austin, TX

#3 Post by Aquitaine »

Hi again,

My apologies for the tone of the first post. I know everyone here is just trying to do the best they can and I really don't mean to discourage it. I've been terribly short on time for FO lately and it's not appropriate of me to take my frustration out on you all. :?

Anyhow, please do feel free to ask whether or not something is appropriate. We're still early on in this process and it will take shape and evolve as we get better at it.

Cheers,
Fwiffo
Surprise and Terror! I am greeted by the smooth and hostile face of our old enemy, the Hootmans! No... the Huge-glands, no, I remember, the Hunams!

Tyreth
FreeOrion Lead Emeritus
Posts: 885
Joined: Thu Jun 26, 2003 6:23 am
Location: Australia

#4 Post by Tyreth »

According to tzlaine's instructions, all techs from now on must be presented in XML format as described above.

A new restriction is also now in effect. It is currently in the effects document that tzlaine linked to, but it is worth us pointing out here so that you are aware:
The only limitations on this as of this writing are that Theory techs can only depend on other Theory techs, and that refinements cannot be prerequisites except for other refinements.
So please make sure that you write contributions for both theories and applications, since no theory may depend on another application tech. We need both to build the tech tree.

If you take care to follow the instructions in this thread, we should be able to get the tech tree for FreeOrion done quicker and with minimal trouble.
Last edited by Tyreth on Tue Dec 14, 2004 2:54 am, edited 1 time in total.

drek
Designer Emeritus
Posts: 935
Joined: Thu Jun 26, 2003 8:07 am

#5 Post by drek »

nice. spelling techs (etc) out in XML here in the forums seems like a good way of doing things.

tzlaine
Programming Lead Emeritus
Posts: 1092
Joined: Thu Jun 26, 2003 1:33 pm

#6 Post by tzlaine »

Tyreth wrote: So please make sure that you write contributions for both theories and applications, since no application may depend on another application. We need both to build the tech tree.
Is this a typo? There is no restriction on apps requiring apps; that's legal, afaik.

Tyreth
FreeOrion Lead Emeritus
Posts: 885
Joined: Thu Jun 26, 2003 6:23 am
Location: Australia

#7 Post by Tyreth »

tzlaine wrote:
Tyreth wrote: So please make sure that you write contributions for both theories and applications, since no application may depend on another application. We need both to build the tech tree.
Is this a typo? There is no restriction on apps requiring apps; that's legal, afaik.
Fixed :oops:

User avatar
utilae
Cosmic Dragon
Posts: 2175
Joined: Fri Jun 27, 2003 12:37 am
Location: Auckland, New Zealand

#8 Post by utilae »

Tyreth wrote: The only limitations on this as of this writing are that Theory techs can only depend on other Theory techs, and that refinements cannot be prerequisites except for other refinements.
So we have to go:

Code: Select all

Theory-------->Application
|
\--------------->Theory
instead of:

Code: Select all

Theory-------->Application
                         |
                         \--------------->Theory


Also, I can't wait for that XML checking program, because I'm finding it a messy job doing techs in XML.

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

#9 Post by Geoff the Medio »

To assist in writing XML tech descriptions, I have compiled the a list of acceptable values for enumerated types, directly from the game code (as of today). This is only a convenience, and may not always be accurate, so to be absolutely sure, you should check the code itself.

http://www.freeorion.org/wiki/index.php ... tion_Enums

drek
Designer Emeritus
Posts: 935
Joined: Thu Jun 26, 2003 8:07 am

#10 Post by drek »

Thanks for the enums documentation Geoff. I'm finding this whole effects system to be pretty impressive; it's a lot more flexible than I thought it would be.

a few quick question, this seems like a good thread to ask in:

1: Although there are no "Events" there are "Specials". Can buildings (or techs for that matter) spawn a special to be attached to the target planet in v.3 or is that unimplemented?

For example, an effect on a building might have a 1% chance each turn of causing a "Pollution" special to be attached to a planet within raidus of effect.

2: 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?

3: Orginally we had conditions for examining and changing aspects of the empires themselves, including conditions for testing/changing stockpiles and (more importantly) testing an empire to determine if it had a certain tech researched.

For example, as in Civ3, there might be certain buildings/techs that stop working once an age tech has been researched. Geoff in particular: can you think of a work around to get something like this to work with the conditions we have? You mentioned something about dummy techs in the Learning thread.

guess: when Age of Exodus is researched, it sets availability of all the obsolete techs to false. A building that can become obsolete is destroyed by the tech, and prehaps replaced with new version of the building. Thinking it might be nice (for execution speed) if there was a way to indicate that an effects group should only be executed once: upon the creation of the object....kind of like a constructor.

drek
Designer Emeritus
Posts: 935
Joined: Thu Jun 26, 2003 8:07 am

#11 Post by drek »

One more thing:

Under the building specification, there is only "Build cost". (unlike techs which have a research cost and research turns)

Does v.3 work differently now, or ???

Aquitaine
Lead Designer Emeritus
Posts: 761
Joined: Thu Jun 26, 2003 1:54 pm
Location: Austin, TX

#12 Post by Aquitaine »

I'm pretty sure buildings should have both a cost and a time. I will have the author flogged.

: flogs self :
Surprise and Terror! I am greeted by the smooth and hostile face of our old enemy, the Hootmans! No... the Huge-glands, no, I remember, the Hunams!

drek
Designer Emeritus
Posts: 935
Joined: Thu Jun 26, 2003 8:07 am

#13 Post by drek »

It just occured to me that we have some limited branching in the tech tree, using the set availability effect:

For example: If a player researches "Robot Slaves" it sets availablity on "Robot Citizens" to False. If the player researches "Robot Citizens", the availability on "Robot Slave" is set to False.

tzlaine
Programming Lead Emeritus
Posts: 1092
Joined: Thu Jun 26, 2003 1:33 pm

#14 Post by tzlaine »

drek wrote:Thanks for the enums documentation Geoff. I'm finding this whole effects system to be pretty impressive; it's a lot more flexible than I thought it would be.

a few quick question, this seems like a good thread to ask in:

1: Although there are no "Events" there are "Specials". Can buildings (or techs for that matter) spawn a special to be attached to the target planet in v.3 or is that unimplemented?

For example, an effect on a building might have a 1% chance each turn of causing a "Pollution" special to be attached to a planet within raidus of effect.
RTFD.
2: 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?
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.
3: Orginally we had conditions for examining and changing aspects of the empires themselves, including conditions for testing/changing stockpiles and (more importantly) testing an empire to determine if it had a certain tech researched.
The stockpile condition and effect are in progress. When they are implemented, they will be added to the documentation. If there is a pressing need to add a Technology-aware Condition, we can add one, but I currently have no such plans.
For example, as in Civ3, there might be certain buildings/techs that stop working once an age tech has been researched. Geoff in particular: can you think of a work around to get something like this to work with the conditions we have? You mentioned something about dummy techs in the Learning thread.

guess: when Age of Exodus is researched, it sets availability of all the obsolete techs to false. A building that can become obsolete is destroyed by the tech, and prehaps replaced with new version of the building. Thinking it might be nice (for execution speed) if there was a way to indicate that an effects group should only be executed once: upon the creation of the object....kind of like a constructor.
This can be acheived by making this Age tech have an Effect that changes the definition of the building in question to do nothing, or to work less well. See the FAQ if you don't follow me.

tzlaine
Programming Lead Emeritus
Posts: 1092
Joined: Thu Jun 26, 2003 1:33 pm

#15 Post by tzlaine »

drek wrote:It just occured to me that we have some limited branching in the tech tree, using the set availability effect:

For example: If a player researches "Robot Slaves" it sets availablity on "Robot Citizens" to False. If the player researches "Robot Citizens", the availability on "Robot Slave" is set to False.
When a Tech is set to "available" in the SetTechAvailability effect, that means that it is available as if you already researched it, so you can research Techs that require it. Setting it to "unavailable" means that it is unkown to your empire. If you know all its prerequisites, you can still research it. If you read the SetTechAvailability entry in the Effects doc closely, you'll see that it says this. There is currently no way to make Techs appear or disappear.

Post Reply