Difference between revisions of "Talk:FOCS Scripting Details"

From FreeOrionWiki
Jump to: navigation, search
m (Dilvish moved page Talk:Effects to Talk:FOCS Scripting Details: make page name more accurate (not limited to Effects))
 
(40 intermediate revisions by 10 users not shown)
Line 1: Line 1:
=Introduction=
+
=Future Ideas=
 +
==Move To Effect==
  
"Effects" are changes/modifications to game objects. 
+
(Self explanitory)
  
"Game Objects" include the player-visible parts of the game simulation, such as empires, systems, planets, buildings, ships and specials.  Game objects may also be invisible to the player, and be used internally by the game to simulate / maintain the gamestate.  Game objects also each contain a group / list of effects.  A particular game object's effects determine many of the ways it iteracts with the other game objects.  For example, a building might have an effect which alters a meter of a planet, or a special attached to a system might make all ships in the system have nonfunctional shields.  A player-visible game object may contain no effects, and a player-invisible game object may contain effects, allowing for flexible in-game grouping of effects that work together by creation of the appropriate game object.
+
==Purgatory==
  
=Game Objects & Effects=
+
Places object into "purgatory" (for lack of better term).  Object is removed from game map, and is not accessible or visible or controllable to players.  Object's attributes / properties / status is otherwise the same (could retain galaxy map position for convenience).  Later, object can be removed from purgatory, and is placed back on galaxy map in exact condition it was when it was removed.  This can be used to represedn "phasing" things out of this universe, or to represent a delay between disappearing at from one place and reappearing somewhere else, such as might be desired for an effects-based movement mechanism, using the "move to" effect.
  
Game objects are of a particular class.  The class description of a game object is contained within an XML file.  This description indicates all the effects the game object contains, all information about how the effects function, a category into which the game object falls (to enable to the game to deal with the object internally, other than through effects), how the object is represented to the player (if it is visible) and any other necessary information about the object.
 
  
Game Object Descriptions include:
+
=Suggested Changes (Sept. 17/18)=
  
*Type - the type of a game object determines how the object is managed by the game code in general.  Specific types may be determined by programmers, but suggestions include buildings, specials, ships, technologies, planets, systems etc.  The "type" of an object is like a general grouping, whereas class is a detailed, specific case of a type.  In practice, "type" may be an object property, or treated as a particular programming code-class.  In either case, "type" needs to be an settable property for objects in XML files, and accessibe for effects in game (see below).
+
==Stacking==
  
*Representation - very dependent on typeIn some cases, a particular visual icon (image file) may be indicated.  Other options to be determined by programmers / graphics designers.
+
Should change stacking to not involve object class.  Stacking number should be the only consideration.  If an two effects could fire on an object and they both have the same stacking number, only one can fireHow to decide which in cases of conflict isn't clear...  For numerical effects, the larger could apply, but we haven't explicitly outlawed preventing stacking of non-numerical effects (with numericals or non-numericals).
  
*Duration - how many turns the game object remains in the game before disappearing on its own.  This may be set to 0, indicating a game object that exists only to group several effects that fire instantly when it is created, may be nonzero positive, indicating a limited duration in turns, or may be negative, indicating an infinite duration game object, that never disappears unless destroyed by an effect (of its own, or another object).
+
'''drek says:'''Agreed.
  
*Effects - a fairly detailed list of effects and information about their functionality.  For each effect in an effects lists, the object description indicates:
+
'''Ellestar:''' Ok, max is in. But how about a diminishing returns stacking type? Well, maybe it's not really essential.
**Effect Class - indication of basic functionality of the effect. See below.
+
Also, how events will be stacked? I suppose, we don't want 2 events "revolution" on one planet. Maybe duration should be reset to a maximum. Or, maybe, duration should be added. Also, what to do with events that don't have a duration? Just don't apply second event to the same target?
**Scope Conditions - a list of scope-limiting conditions that determine what game objects the effect fires upon, in addition to any restrictions implied by the effect class.  See below.
+
**Parameters - details about how an effect should function. Needed for details of the how the effect class functions and most of the scope limiting conditions.
+
  
=Effects for v0.3:=
+
==Scope Conditions==
  
*Modify Planet Max Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's max meters this turnDoes not affect current meter values.
+
Should remove inclusive / exclusive conditions.  Should say that ideally all conditions could be used in either capacity, but programmers are free to put limits on this if they feel it is necessary / beneficial / easier to do soCould suggest not using "expensive" to calculate conditions for inclusion (eg. distance from source).
  
*Modify Planet Current Meter (Specified Amount, Specified Meter) - Adds or subtracts from a planet's current meter values.  Does not affect max meter values.
+
'''drek says:''' Not thrilled, but fine, if it'll end that thread.
  
*Modify Empire Stockpile (Specified Amount, Specified Resourse) - Adds or subtracts from one of empire's stockpiles.
+
==Random Parameter Values==
  
*Modify Planet Size/Environment (Specified Environment) - Sets the size and environment of a planet
+
Remove!
  
*Create Object (Specified Object Class) - Creates a new game object.  If applicable, location and empire ownership are the same as the game object being fired on by the effect.  This is obviously a rather complicated and multi-functional effect, with numerous possible variations in behaviour depending on the types and number of game objects being created.  As such, it may be more convenient to separate this effect into numerous separate effects in order to create objects of any given category (buildings, ships, specials, etc.) which appropriate parameters for each.  The specifics of this are left for programmer judgement to decide.
+
'''drek says:''' Ok.
  
*Destroy Object - Destroys a game object.
+
==Turn Processing Order==
  
*Set Empire Research (Specified Technology, Specified Yes/No) - Sets a tech a researched or not reserached for empire.
+
*Set all max meters to 0.  Current meter values remain unchanged from previous turn's values.
 +
*Fire all meter altering effects:
 +
**Max meter values are added to to by primarily effects that consistently fire every turn, establishing a consistent max meter value
 +
**Current meter values may be modified by effects as well, but rarely compared to current meter values, and primarily by one-shot effects, rather than effects that consistently fire every turn, as this would cause the current meter value to grow very much each turn.
 +
*Apply current meter growth formula (not based on effects)
 +
*Cap current meters by max meter values as applicable
 +
*Fire all non-meter-altering effects
 +
*Do rest of turn
  
*Set Empire Building Availability (Specified Building Class, Specified Buildable / Not Buildable) - Sets a building type as buildable or not for empire.
+
Note that meter altering effects fire before ship movement, or anything else, so ship move orders given in turn N do not affect meter values in turn N+1, but do affect meter values in turn N+2.
  
*Set Ship Type Availability (Specified Ship Class, Specified Buildable / Not Buildable) - Sets a ship class as buildable or not buildable for empire.
+
In future there may be seveal times during a turn when a non-meter-altering effect can fire.  This will occur before, after and between thing like ship movement, production/popgrowth/research and combat.  Effects-altering meters will always happen at the very start of a turn, however, before anything else, effects or otherwise.
  
*Set Star Colour (Specified Star Colour) - Sets the colour of a star.
+
'''drek says:''' Seems ok.
  
 +
Ellestar: IMHO a check if a planet is blockaded should go before an effects phase and before ship movement phase. That way, ships that arrived in a previous turn will blockade a planet by applying an effect on a planet.
  
=Effect Scope and Scope-Limiting Conditions=
+
Geoff:  No blockading in v0.3, as far as I know.
  
The set of game objects (planets, ships, stars, buildings, specials) that are fired upon by an effect are collectively known as the effect's scope.  The scope of an effect is defined by a set of conditions which may exclude game objects from the set.  The scope of an effect is all objects in the game by default, and is reduced by the various scope-limiting conditions for each effect.  The conditions are evaluated at the time the effect fires, so an object may be part of an effect's scope for one firing, but not another firing.  All conditions are exclusive: applying a condition to a scope set for an effect can only remove objects from the scope, or leave the scope unchanged, and can never add more objects back into the scope that were previously removed by other conditions.  Thus, the order in which conditions are applied does not affect the contents of the final scope set fired upon by the effect.
+
==Technology as Game Object?==
  
Conditions are checks of various properties of game objects.  Some conditions are based on properties of objects themselves, and others depend on other objects associated with the object being checked by the conditionFor example, a building may be checked for exclusion from the scope according to a planet environment condition.  The building itself has no planet environment, however the building is attached to a planet, so the environment of the planet is check for the purposes of determining whether the building is excluded from the scope of the effect. Attachments form a tree, so if the building was checked by a condition for a property that neither it nor the planet it is attached to have (such as star colour), the system in which the planet is located would be checked.  If no objects in the tree of attached objects for a given potential scope object have a property being checked for, then the object is excluded by default.  For example, if a ship was checked for star colour while it was not in any star system, the ship would be excluded from the scope of the effect by default.
+
When a technology is researched / gained, it might be implimented as a game-created 0 duration game object that has effects which unlock other classes of game object for the playerA separate infinite-duration game object could simultaneously be created to give persistant benefits of the technology as well. Alternatively, a persistant actor labelled as a special could be attached to an empire, bestowing some benefits.
  
If a condition description (below) states that it restriction objects by some property, or "their" some property, the hierarchy is used when necessary to determine what value of the property applies to the game object.
+
Technology could also not be treated as a game object at all, but rather as a special internal system unrelated to game objects, and having a separate content description scheme.  Presumably it would be easier, efficient and faster to use the same system as much as possible though.  In practice, construction of game objects like "buildings" through non-effects based planet production is probably quite similar to researching a technology treated as a game object through non-effects based research.
  
The hierarchy of attachment for scope condition purposes in v0.3:
+
'''Drek says:'''  my guess is tzlaine would not be pleased to see either of these paragraphs in design doc.  Let's just be silent on the issue of how tech is implemented.  Doesn't matter if it's a pair of objects, a single object, or a flag in a list.
  
*Buildings are attached to the planet on which they are located.
 
*Planets are attached to the system in which they are located.
 
*Ships are attached to the system in which they are located (if applicable), or nothing (if not in a system).
 
*Specials are attached to the game object they are associated with (as / if applicable)
 
  
Note that the hierarchy described above is only used when checking for a property not specified for a given game object.  This is used only when necessary, and not in cases of possible conflict with another condition, should such a situation arise (though none are yet anticipated).
+
==Effect Group Activation Conditions==
  
Note also that targetting of empires, as opposed to other game objects owned by empires, may be "loose".  This this, it is meant that an effect that is described above as setting some property of a particular empire may be targetted to that empire directly, or may affect all empires that own an object that falls into the effect's scope.  The specifics of how this works can be decided by programmers, but it should be possible to target an empire directly, or target all empire's that own other objects objects in an effect's scope.
+
Need to add a variety of conditions, similar to scope conditions, but dependent on properties of the source object (and dependencies via hierarchy), and which determine whether the effects group is "on" for a given turnShould include conditions for:
 +
*properties of owner empire / presence of special attached to owner empire (for empire-wide special resources perhaps)
 +
*focus setting
 +
*stockpiles
 +
*co-located with object of type/class/category
 +
*within X distance/jumps
  
 +
Actually... most of the scope conditions should be usable, though there'll be a few extras that only apply to source objects
  
=Scope-Limiting Conditions for v0.3=
+
Maintainance fees (or resource requirements and consumption while active) would also be nice to have as an acitvation condtion, as would some sort of player controlled turning on / off.  How to do this is a bit unclear however, since effects fire at the very start of a turn, before the game would have a chance to deduct maintainance fees (or collect taxes with which to pay them).  We could perhaps determine if fees will / can be paid before firing effects, or we could have have things deactivate at the end of a turn if their maintainance is unpaid, rather than deactivating the effect during the turn when the shortfall would occur.
  
*Planet Environment (Specified Type, Range) - Excludes objects from the scope if they are more than a specified range of environments types away from the specified environment type.  If the specified environment is not on the EP wheel, then the specified range is ignored, and the scope objects' environments must the specified environment exactlyIf the specified environment is on the wheel, but a scope object's environment is not, then the scope object is excluded.  The specified type of environment may be either an actual environment type (eg. "ocean"), or may be set to use the environment of the source object for the effect.  In this case, if the source object has no environment, all objects are excluded from the effect scope.
+
Any effect group that includes an effect that modifies meter(s) cannot use meter value as an activation conditionAs such, it seems that it will be necessary to not have meter values as an activation condition for effects groups.
  
*Planet Size (Specified Size, Range) - Excludes objects from the scope if they are more than a specified range of planet sizes away from the specified planet sizeThe specified size may be either an actual size type (eg. tiny), or may be set relative to the source object for the effect.  In this case, if the source object has no planet size, all objects are excluded from the effect scope.
+
'''Drek says:''' sounds greatco-located and distance can possibly be combined into a single condition
  
*Star Colour (Specified Colour) - Excludes objects from the scope if their star colour does not match the specified colour.  The specified colour may be either an actual colour (eg. blue), or may be set relative to the source object for the effect.  In this case, if the source object has no star colour, all objects are excluded from the effect scope.
+
'''Ellestar:''' Why there is no *random (restricted only for events that don't modify meters) and *meter value activation condition? We need both for random events, and it's better to have *meter value activation condition for buildings (check for a last turn meter value).
  
*Object Type (Specified Type) - Excludes objects from the scope if their game object type does not match the specified object type.  The specified type maybe a an actual type (eg. ship, building, special, planet), or may be set relative to the source object for the effect.  If programmers elect to do so, "empire" might be an valid object type, allowing an effect to target empires directly, as opposed to targetting other game objects owned by an empire to get at the empire itself.
+
==Side Note: Effect Group Exclusivity==
  
*Direct Distance (Specified Distance) - Excludes objects from the scope if their physical location on the galaxy map is not within a specified distance from the source object's location.  If the source object or any of the scope objects have no physical location on the galaxy map, then all or the relevant scope objects are excluded, respectively.
+
Should perhaps say that effect groups may only have effects that alter meters or that do not alter meters, not a mix...
  
*Starlane Jumps (Specified Number) - Excludes objects from the scope if their physical location is not within a specified number of starlane jumps from the source objectIf the source object is located at a system, then all systems connected to the source object's system by one starlane jump are at a distance 1, by two starlane jumps are at a distance 2, and so on.  Objects on starlanes between systems count as being one jump away from either starlane at the end of the lane they are on.  Objects are always considered to be the shortest number of starlane jumps away from the source as possible, whether or not the starlanes involved are known to the empire(s) involved.
+
'''Drek says:''' not importantGame can simply store effects for firing later in turn processing.
  
*Empire Affiliation (Specifed Source Empire, Enemies Inclusive, or Enemies Exclusive) - Excludes objects from the scope based on the empire they are affiliated with.  The condition may be specified to apply to objects owned by the empire that owns the source object only, to empires other than the source empire in both an inclusive and exclusive sense.  (more options will be added after diplomacy).  The "owner" of an object is generally clear, as in a ship or planet, which is clearly owned by a particular empire.  Systems containing planets owned by two or more empires are owned by all empires that own planets in the system.  In this case, "Enemies Inclusive" would include any system that contains a planet owned by an empire other than the source object's empire, and "Enemies Exclusive" would exclude systems that contain planets owned by both the source object's empire an another empire.
+
'''Ellestar:''' That's why i said that you'll need to store effects to run them in a later priority stages. A system with effects that can create other effects (or effect groups in your document) is more flexible.
  
*Chance (Specified Probability) - Excludes objects from the scope randomly. Each object is given its own "dice roll", the value of which is compared to the specified probability.  If the roll is less than the parameter, then the object is excluded form the scope.
+
Geoff:  No priority stages in v0.3, other than meter-altering and not-meter-altering.
  
*Stacking (Specified Integer) - If the specified integer, or "Stacking Number" is 0, the effect can be fired on a given game object any number of times in a given turn. If the stacking number is nonzero, effects of a given effect class will have a game object removed from their scope if another effect of the same class and stacking number has already fired on the scope object in a given turn.
+
'''Ellestar:''' And you need it to have effects of one effect group in a different priority stages (like meter-altering and not-meter-altering) so not to have this restriction.
  
*Current Meter Value (Specified Meter, Specified Value) -  
+
==Non-Effects Game Object Info==
  
*Scope Object Visible To Source Object (Specified True / False) -
+
Yoghurt was going to work up some stuff about coding objects in Python... don't know what's happening with that...
  
*Source Object Visible To Scope Object (Specified True / False) -
+
Game object descriptions will need some non effects info.  For v0.3, this could be:
 +
*Buildings require a prerequisite tech, a cost per turn, a construction time in turns, a name, and all the effects stuff.
 +
*"Specials" can be randomly assigned at the start of the game to planets. They require just a name and a list of effects.
 +
*Planets, ships, systems, empires, etc. all are treated effectively like they are in v0.2, except that they can be in the scope of an effect and have a few properties that can be modified by effects. 
  
*Current Stockpile Value (Specified Resource, Specified Value) -
+
There is no player ship desgin in v0.3, so ships could be coded as a temporary class of scripted object (object class = MarkIV or somesuch).  In future, presumably the ship design component will make internally self-scripted object classes (or something similar), which ship game objects will use as their object class.
  
*Co-located with Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not at the same physical location on the galaxy map as an object of the specified class.  This could be used to exclude ships from the scope if they are not located in a system with a particular special on one of its planets, for example.
+
For v0.3, only buildings and specials can have effects (?), which are encoded in Python XML.  This might be extended to include technologies, if programmers are so inclined.
  
*Attached to Object of Class (Specified Class of Game Object) - Excludes objects from the scope if they are not attached to an object of the specified class. This could be used to exclude planets from the scope if they do not have a particular type of building located on them.
+
'''Drek says:''' Doesn't matter if it's expressed in Python, XML, comma seprated text fields, or punchcards.  (XML, btw, is a completely different animal from PythonShould probably remove all references to XML, simply call them "content files" or something like that.
  
=TO DO: Order of effect firing=
+
I'd leave out mention of specials until they are slated by Aq.  We need to chat with him on when they are to be added to the document.
 +
 
 +
Buildings can have multiple prerequests, including technology, planet specials (I know, contradicting myself in the span a two lines), and most importantly planet focus.  That buildings can have a planet focus prerequisite was the subject an an early public review, one of Aq's pet ideas.
 +
 
 +
* Technologies: require a prerequisite tech, a cost per turn, a research time in turns, a name, and all the effects stuff.
 +
 
 +
==Unlocking?==
 +
 
 +
Techs or specials or whatever that "unlock" things for empires to build (or research?) could work either of two ways:
 +
*The "unlocked" status of an object could be stored as part of the empire or the object itself, and be persistant.  The "unlock" effect would only need to fire once, and the object is unlocks would stay unlocked until relocked by some other effect
 +
*The "unlocking" effect needs to fire every turn, and a persistant object needs to exist to hold and fire the effect.
 +
 
 +
I'm inclined to suggest the first option.
 +
 
 +
'''Drek says:''' Agreed, the first.
 +
 
 +
==Some Explanitory Text?==
 +
 
 +
Each effects group is a list of one or more effects. There can be more than one effects group in a game object, so the object description has "effects groups". The first quoted statement was a point in a list of things in an object description, one of which was the effects groups that the object contains. Similarly, the effects part of an effects group is a list of the classes and parameters for the effects in the effects group.
 +
 
 +
==New Scope Condition?==
 +
 
 +
Something along the lines of "has meter of type X" might be helpful, though this could probably be implimented automatically by the "set meter value" effect, which would only work on objects with the specified type of meter.
 +
 
 +
'''Drek says:''' I don't see the need.  Can happen, as you suggest, automatically.  If a condition or effect references a non-existant meter, it fails. 
 +
 
 +
'''Ellestar:''' And, as i said, you don't need "All objects" scope condition because "All objects" don't have all meters, can't be targets of any non-metered effect etc. It should be "All valid objects" because of the same reason. If an object is not need, there is no need to add it in the first place, and a program can decide that a program don't need this object type in a list of scope objects. My thoughts about that are scattered in 3-4 posts in 1-2 page of the discussion. Conditions that check object type should only further reduce a list of avaliable objects, "All valid objects" should be a default scope condition.
 +
 
 +
==List of fired and unfired effects==
 +
 
 +
It will helpful to have the game player client maintain a list (aka "ledger") of effects that are expected to fire or expected to not fire on object while the player is giving orders.  Based on the current orders, the game will predict meter values for all meters for the next turn.  If the player alters an order which changes the prediction, it's desirable to have an immediately accessible list of effects that could fire on the object.  This is better / faster than having to iterate through all effects in the game every time a player changes an order that could cause a scope condition to change a particular effect form firing or not firing on a particular object or set of objects.
 +
 
 +
(For effect activation conditions, it's only necessary to check the effects of the object whose orders were changed.  Any effects it has that are turned on or off as a result of the order change can be reapplied or unapplied to all relevant game objects)
 +
 
 +
'''Drek says:''' Yes, for each meter, and perhaps the stockpiles as well.  Beyond the use you described above, the list would be available for player to read via a method to be determined by the UI team.  (for example, a tooltip hovering over a meter meter might detail the effects that acted on the meter.)  For this reason, each effect needs a name and possibly a description.
 +
 
 +
==Multiplication Factors?==
 +
 
 +
Current there are no "modify meter multiplier" effects, which IMO is as it should be, but if we want one, we should specify how they'd work (so that ordering of additive and multiplicative bonuses doesn't matter).
 +
 
 +
"Multiplication should be stored separately from meter value, so if you start with a meter of 5, and a multiplicatin of 1, then make the multiplier 2, then add 5 to the meter, you end up with a meter of 10 and a multiplier of 2... ie. the multiplier is multiplied by the meter value only at the exact moment you evaluate the total meter value. Adding to a meter after adding to a multiplier only changes the root meter value, which is unaffected by changing the multiplier value."
 +
 
 +
'''Drek says:''' Sounds like a convoluted way of describing a simple concept.
 +
 
 +
Each max and current meter has a multipler.  At the start of turn processing, all multipliers are set to a value of 1.  (suchandsuchEffect) adds to these multipliers.  At stage (whatever) the multipliers attached to max meters are multiplied with each max meter.  At stage (whatever) the multipliers attached to current meters are multiplied with each current meter.
 +
 
 +
hrm, what I just wrote probably reads like crap.  nevermind.
 +
 
 +
'''Ellestar:''' Is it a good idea to use multiplications? Now, maximum value of a meter is capped at 100, and we have a +15 bonus only from focus. Now, if we have one multiplication of *2, then a bonus of +35 can already give a maximum value.
 +
I thought about divisions to make a more strong penalties. If a planet have +60 health, then a penalty of -10 for the lack of food doesn't look really significant. Now, if we're using a penalty "after calculating a meter value, reduce a health meter by -10 or -30%, whatever is more), then it will be more important.
 +
 
 +
Geoff:  There are no multiplication effects in v0.3.  If we did though, multiplications could be on the order of 1.05 or 1.20, rather than 2 or 5.  Division can be represented by multipliers of less than 1.
 +
 
 +
==Do we need to show the previous turn's meter values?==
 +
 
 +
drek: "Maybe not on the sidebar, but it should be somewhere.
 +
 
 +
Otherwise, how can the player review the effects of events that only last a single turn?"
 +
 
 +
Geoff: "This probably needs to be dealt with on a case-by-case basis as well... I imagine most single-turn events would have sitrep notes though, or be something that the player knew about the turn before, so were already incorporated into the client UI's prediction of the relevant meter values during the previous turn (eg. in the case of ships which only modify a meter for one turn due to moving or somesuch)."
 +
 
 +
'''Drek says:''' I'm thinking of single turn events, like Earthquakes or whatever.  Or events with unpredictable durations, like Riots.  Doesn't hurt things to have last turn's values listed -somewhere-.
 +
 
 +
'''Ellestar:''' Hmm. If you're calculating meters first, then random events (and everything else too) will be generated at a later stage (besides, in examples on forums a lot of them take meter values as parameters, so they should be either generated later than meter-altering effects or take values from a previous turn). So, if random events will be generated at a later stages, then a player will see a report about an event from a server, but an event will have an effect on a meters only at the start of the next turn, and that can be predicted by a client.
 +
But, of course, player should see last turn values. That way, he'll be able to see progress by comparing last turn values and predicted values.
 +
 
 +
Geoff:  In future, it might be good to have an "Object Age" or "Universe Age / Year" activation condition, as well as a way to turn on/off visibility of an object to a player using effects.  Thus an event could be made one turn, but stay invisible, then appear the next turn and be visible and have meter-altering effects on the same turn it becomes visible.
 +
 
 +
That said, for now we could make on object that is a "potential event" with a chance activation condition on an effect group that has effects that do whatever the event is supposed to do.  Programmers could make the event visible to the player (or post a sitrep) only if the relevant effects group is active in a given turn.
 +
 
 +
==Explain Intention of Effects Groups==
 +
 
 +
drek: Possibly rewrite the effect groups blurb to make it more obvious what the intention is. (grouping a bunch of effects together so that conditions only need to be calculated once)
 +
 
 +
Mockup for fake XML as reference (shouldn't be in actual design, probly):
 +
 
 +
ObjectClass WonderFarm {
 +
    Category = Building
 +
    Cost = 5
 +
    Buildtime = 10
 +
    PrereqTech = WonderFarming
 +
    EffectGroup {
 +
        Effect {
 +
            EffectClass = ModifyMeter
 +
            Meter = Farming
 +
            Amount = 5
 +
        }
 +
        Effect {
 +
            EffectClass = ModifyStockpile
 +
            Resource = Food
 +
            Amount = 113
 +
        }
 +
        ScopeCondition {
 +
            ConditionClass = ObjectType
 +
            ObjectType = Planets
 +
        }
 +
    }
 +
    EffectGroup {}
 +
}
 +
'''Drek says:''' This looks like scripting code (like Python).
 +
 
 +
XML is HTML, cept you get to make up the tags.
 +
 
 +
<object type=Building name=Wonderfarm cost=5>  <prereq> pretech=WonderFarming prewhatever=blah </prereq> <EffectGroup> <Conditions> condition blah blah </conditions> <effects> blah blah blah </effects> </EffectGroup> </object>
 +
 
 +
I wouldn't worry about this.  The programmers will come up with something, then someone (probably me, you, or the guy who coded it) will document the format.  It's the sort of thing that's debated on the programming list; if your interested in this sort of thing, might want ask tzlaine to sign you up for that list.
 +
 
 +
Thanks for dealing with this.  I lost patience with it weeks ago.
 +
 
 +
heh.
 +
 
 +
= Clarification or link needed =
 +
 
 +
In many of the topics there is a note about name and description:
 +
<pre>"The note about Special name and description text also applies to xxx"</pre>
 +
 
 +
I do not see any specific notes for these.  If one is added, or already exists, a link to the note may be helpful.

Latest revision as of 00:14, 25 September 2017

Future Ideas

Move To Effect

(Self explanitory)

Purgatory

Places object into "purgatory" (for lack of better term). Object is removed from game map, and is not accessible or visible or controllable to players. Object's attributes / properties / status is otherwise the same (could retain galaxy map position for convenience). Later, object can be removed from purgatory, and is placed back on galaxy map in exact condition it was when it was removed. This can be used to represedn "phasing" things out of this universe, or to represent a delay between disappearing at from one place and reappearing somewhere else, such as might be desired for an effects-based movement mechanism, using the "move to" effect.


Suggested Changes (Sept. 17/18)

Stacking

Should change stacking to not involve object class. Stacking number should be the only consideration. If an two effects could fire on an object and they both have the same stacking number, only one can fire. How to decide which in cases of conflict isn't clear... For numerical effects, the larger could apply, but we haven't explicitly outlawed preventing stacking of non-numerical effects (with numericals or non-numericals).

drek says:Agreed.

Ellestar: Ok, max is in. But how about a diminishing returns stacking type? Well, maybe it's not really essential. Also, how events will be stacked? I suppose, we don't want 2 events "revolution" on one planet. Maybe duration should be reset to a maximum. Or, maybe, duration should be added. Also, what to do with events that don't have a duration? Just don't apply second event to the same target?

Scope Conditions

Should remove inclusive / exclusive conditions. Should say that ideally all conditions could be used in either capacity, but programmers are free to put limits on this if they feel it is necessary / beneficial / easier to do so. Could suggest not using "expensive" to calculate conditions for inclusion (eg. distance from source).

drek says: Not thrilled, but fine, if it'll end that thread.

Random Parameter Values

Remove!

drek says: Ok.

Turn Processing Order

  • Set all max meters to 0. Current meter values remain unchanged from previous turn's values.
  • Fire all meter altering effects:
    • Max meter values are added to to by primarily effects that consistently fire every turn, establishing a consistent max meter value
    • Current meter values may be modified by effects as well, but rarely compared to current meter values, and primarily by one-shot effects, rather than effects that consistently fire every turn, as this would cause the current meter value to grow very much each turn.
  • Apply current meter growth formula (not based on effects)
  • Cap current meters by max meter values as applicable
  • Fire all non-meter-altering effects
  • Do rest of turn

Note that meter altering effects fire before ship movement, or anything else, so ship move orders given in turn N do not affect meter values in turn N+1, but do affect meter values in turn N+2.

In future there may be seveal times during a turn when a non-meter-altering effect can fire. This will occur before, after and between thing like ship movement, production/popgrowth/research and combat. Effects-altering meters will always happen at the very start of a turn, however, before anything else, effects or otherwise.

drek says: Seems ok.

Ellestar: IMHO a check if a planet is blockaded should go before an effects phase and before ship movement phase. That way, ships that arrived in a previous turn will blockade a planet by applying an effect on a planet.

Geoff: No blockading in v0.3, as far as I know.

Technology as Game Object?

When a technology is researched / gained, it might be implimented as a game-created 0 duration game object that has effects which unlock other classes of game object for the player. A separate infinite-duration game object could simultaneously be created to give persistant benefits of the technology as well. Alternatively, a persistant actor labelled as a special could be attached to an empire, bestowing some benefits.

Technology could also not be treated as a game object at all, but rather as a special internal system unrelated to game objects, and having a separate content description scheme. Presumably it would be easier, efficient and faster to use the same system as much as possible though. In practice, construction of game objects like "buildings" through non-effects based planet production is probably quite similar to researching a technology treated as a game object through non-effects based research.

Drek says: my guess is tzlaine would not be pleased to see either of these paragraphs in design doc. Let's just be silent on the issue of how tech is implemented. Doesn't matter if it's a pair of objects, a single object, or a flag in a list.


Effect Group Activation Conditions

Need to add a variety of conditions, similar to scope conditions, but dependent on properties of the source object (and dependencies via hierarchy), and which determine whether the effects group is "on" for a given turn. Should include conditions for:

  • properties of owner empire / presence of special attached to owner empire (for empire-wide special resources perhaps)
  • focus setting
  • stockpiles
  • co-located with object of type/class/category
  • within X distance/jumps

Actually... most of the scope conditions should be usable, though there'll be a few extras that only apply to source objects

Maintainance fees (or resource requirements and consumption while active) would also be nice to have as an acitvation condtion, as would some sort of player controlled turning on / off. How to do this is a bit unclear however, since effects fire at the very start of a turn, before the game would have a chance to deduct maintainance fees (or collect taxes with which to pay them). We could perhaps determine if fees will / can be paid before firing effects, or we could have have things deactivate at the end of a turn if their maintainance is unpaid, rather than deactivating the effect during the turn when the shortfall would occur.

Any effect group that includes an effect that modifies meter(s) cannot use meter value as an activation condition. As such, it seems that it will be necessary to not have meter values as an activation condition for effects groups.

Drek says: sounds great. co-located and distance can possibly be combined into a single condition

Ellestar: Why there is no *random (restricted only for events that don't modify meters) and *meter value activation condition? We need both for random events, and it's better to have *meter value activation condition for buildings (check for a last turn meter value).

Side Note: Effect Group Exclusivity

Should perhaps say that effect groups may only have effects that alter meters or that do not alter meters, not a mix...

Drek says: not important. Game can simply store effects for firing later in turn processing.

Ellestar: That's why i said that you'll need to store effects to run them in a later priority stages. A system with effects that can create other effects (or effect groups in your document) is more flexible.

Geoff: No priority stages in v0.3, other than meter-altering and not-meter-altering.

Ellestar: And you need it to have effects of one effect group in a different priority stages (like meter-altering and not-meter-altering) so not to have this restriction.

Non-Effects Game Object Info

Yoghurt was going to work up some stuff about coding objects in Python... don't know what's happening with that...

Game object descriptions will need some non effects info. For v0.3, this could be:

  • Buildings require a prerequisite tech, a cost per turn, a construction time in turns, a name, and all the effects stuff.
  • "Specials" can be randomly assigned at the start of the game to planets. They require just a name and a list of effects.
  • Planets, ships, systems, empires, etc. all are treated effectively like they are in v0.2, except that they can be in the scope of an effect and have a few properties that can be modified by effects.

There is no player ship desgin in v0.3, so ships could be coded as a temporary class of scripted object (object class = MarkIV or somesuch). In future, presumably the ship design component will make internally self-scripted object classes (or something similar), which ship game objects will use as their object class.

For v0.3, only buildings and specials can have effects (?), which are encoded in Python XML. This might be extended to include technologies, if programmers are so inclined.

Drek says: Doesn't matter if it's expressed in Python, XML, comma seprated text fields, or punchcards. (XML, btw, is a completely different animal from Python) Should probably remove all references to XML, simply call them "content files" or something like that.

I'd leave out mention of specials until they are slated by Aq. We need to chat with him on when they are to be added to the document.

Buildings can have multiple prerequests, including technology, planet specials (I know, contradicting myself in the span a two lines), and most importantly planet focus. That buildings can have a planet focus prerequisite was the subject an an early public review, one of Aq's pet ideas.

  • Technologies: require a prerequisite tech, a cost per turn, a research time in turns, a name, and all the effects stuff.

Unlocking?

Techs or specials or whatever that "unlock" things for empires to build (or research?) could work either of two ways:

  • The "unlocked" status of an object could be stored as part of the empire or the object itself, and be persistant. The "unlock" effect would only need to fire once, and the object is unlocks would stay unlocked until relocked by some other effect
  • The "unlocking" effect needs to fire every turn, and a persistant object needs to exist to hold and fire the effect.

I'm inclined to suggest the first option.

Drek says: Agreed, the first.

Some Explanitory Text?

Each effects group is a list of one or more effects. There can be more than one effects group in a game object, so the object description has "effects groups". The first quoted statement was a point in a list of things in an object description, one of which was the effects groups that the object contains. Similarly, the effects part of an effects group is a list of the classes and parameters for the effects in the effects group.

New Scope Condition?

Something along the lines of "has meter of type X" might be helpful, though this could probably be implimented automatically by the "set meter value" effect, which would only work on objects with the specified type of meter.

Drek says: I don't see the need. Can happen, as you suggest, automatically. If a condition or effect references a non-existant meter, it fails.

Ellestar: And, as i said, you don't need "All objects" scope condition because "All objects" don't have all meters, can't be targets of any non-metered effect etc. It should be "All valid objects" because of the same reason. If an object is not need, there is no need to add it in the first place, and a program can decide that a program don't need this object type in a list of scope objects. My thoughts about that are scattered in 3-4 posts in 1-2 page of the discussion. Conditions that check object type should only further reduce a list of avaliable objects, "All valid objects" should be a default scope condition.

List of fired and unfired effects

It will helpful to have the game player client maintain a list (aka "ledger") of effects that are expected to fire or expected to not fire on object while the player is giving orders. Based on the current orders, the game will predict meter values for all meters for the next turn. If the player alters an order which changes the prediction, it's desirable to have an immediately accessible list of effects that could fire on the object. This is better / faster than having to iterate through all effects in the game every time a player changes an order that could cause a scope condition to change a particular effect form firing or not firing on a particular object or set of objects.

(For effect activation conditions, it's only necessary to check the effects of the object whose orders were changed. Any effects it has that are turned on or off as a result of the order change can be reapplied or unapplied to all relevant game objects)

Drek says: Yes, for each meter, and perhaps the stockpiles as well. Beyond the use you described above, the list would be available for player to read via a method to be determined by the UI team. (for example, a tooltip hovering over a meter meter might detail the effects that acted on the meter.) For this reason, each effect needs a name and possibly a description.

Multiplication Factors?

Current there are no "modify meter multiplier" effects, which IMO is as it should be, but if we want one, we should specify how they'd work (so that ordering of additive and multiplicative bonuses doesn't matter).

"Multiplication should be stored separately from meter value, so if you start with a meter of 5, and a multiplicatin of 1, then make the multiplier 2, then add 5 to the meter, you end up with a meter of 10 and a multiplier of 2... ie. the multiplier is multiplied by the meter value only at the exact moment you evaluate the total meter value. Adding to a meter after adding to a multiplier only changes the root meter value, which is unaffected by changing the multiplier value."

Drek says: Sounds like a convoluted way of describing a simple concept.

Each max and current meter has a multipler. At the start of turn processing, all multipliers are set to a value of 1. (suchandsuchEffect) adds to these multipliers. At stage (whatever) the multipliers attached to max meters are multiplied with each max meter. At stage (whatever) the multipliers attached to current meters are multiplied with each current meter.

hrm, what I just wrote probably reads like crap. nevermind.

Ellestar: Is it a good idea to use multiplications? Now, maximum value of a meter is capped at 100, and we have a +15 bonus only from focus. Now, if we have one multiplication of *2, then a bonus of +35 can already give a maximum value. I thought about divisions to make a more strong penalties. If a planet have +60 health, then a penalty of -10 for the lack of food doesn't look really significant. Now, if we're using a penalty "after calculating a meter value, reduce a health meter by -10 or -30%, whatever is more), then it will be more important.

Geoff: There are no multiplication effects in v0.3. If we did though, multiplications could be on the order of 1.05 or 1.20, rather than 2 or 5. Division can be represented by multipliers of less than 1.

Do we need to show the previous turn's meter values?

drek: "Maybe not on the sidebar, but it should be somewhere.

Otherwise, how can the player review the effects of events that only last a single turn?"

Geoff: "This probably needs to be dealt with on a case-by-case basis as well... I imagine most single-turn events would have sitrep notes though, or be something that the player knew about the turn before, so were already incorporated into the client UI's prediction of the relevant meter values during the previous turn (eg. in the case of ships which only modify a meter for one turn due to moving or somesuch)."

Drek says: I'm thinking of single turn events, like Earthquakes or whatever. Or events with unpredictable durations, like Riots. Doesn't hurt things to have last turn's values listed -somewhere-.

Ellestar: Hmm. If you're calculating meters first, then random events (and everything else too) will be generated at a later stage (besides, in examples on forums a lot of them take meter values as parameters, so they should be either generated later than meter-altering effects or take values from a previous turn). So, if random events will be generated at a later stages, then a player will see a report about an event from a server, but an event will have an effect on a meters only at the start of the next turn, and that can be predicted by a client. But, of course, player should see last turn values. That way, he'll be able to see progress by comparing last turn values and predicted values.

Geoff: In future, it might be good to have an "Object Age" or "Universe Age / Year" activation condition, as well as a way to turn on/off visibility of an object to a player using effects. Thus an event could be made one turn, but stay invisible, then appear the next turn and be visible and have meter-altering effects on the same turn it becomes visible.

That said, for now we could make on object that is a "potential event" with a chance activation condition on an effect group that has effects that do whatever the event is supposed to do. Programmers could make the event visible to the player (or post a sitrep) only if the relevant effects group is active in a given turn.

Explain Intention of Effects Groups

drek: Possibly rewrite the effect groups blurb to make it more obvious what the intention is. (grouping a bunch of effects together so that conditions only need to be calculated once)

Mockup for fake XML as reference (shouldn't be in actual design, probly):

ObjectClass WonderFarm {
    Category = Building
    Cost = 5
    Buildtime = 10
    PrereqTech = WonderFarming
    EffectGroup {
        Effect {
            EffectClass = ModifyMeter
            Meter = Farming
            Amount = 5
        }
        Effect {
            EffectClass = ModifyStockpile
            Resource = Food
            Amount = 113
        }
        ScopeCondition {
            ConditionClass = ObjectType
            ObjectType = Planets
        }
    }
    EffectGroup {}
}

Drek says: This looks like scripting code (like Python).

XML is HTML, cept you get to make up the tags.

<object type=Building name=Wonderfarm cost=5> <prereq> pretech=WonderFarming prewhatever=blah </prereq> <EffectGroup> <Conditions> condition blah blah </conditions> <effects> blah blah blah </effects> </EffectGroup> </object>

I wouldn't worry about this. The programmers will come up with something, then someone (probably me, you, or the guy who coded it) will document the format. It's the sort of thing that's debated on the programming list; if your interested in this sort of thing, might want ask tzlaine to sign you up for that list.

Thanks for dealing with this. I lost patience with it weeks ago.

heh.

Clarification or link needed

In many of the topics there is a note about name and description:

"The note about Special name and description text also applies to xxx"

I do not see any specific notes for these. If one is added, or already exists, a link to the note may be helpful.