EvalRule Script - Revision history

Rob: /* Technical Details */

2009-02-20T10:05:55Z

Technical Details

← Older revision		Revision as of 10:05, 20 February 2009
Line 34:		Line 34:
	\|summary		\|summary
	\|(String) Entry: Contains the default summary text if the rule is not satisfied.<br>		\|(String) Entry: Contains the default summary text if the rule is not satisfied.<br>
	Exit: Contains the final summary text to display if the rule is not satisfied.		Exit: Contains the final summary text to display if the rule is not satisfied. If not specified, but the "message" symbol is modified, the summary automatically uses the message text.
	\|-		\|-
	\|}		\|}

Rob: /* Technical Details */

2009-02-20T08:44:52Z

Technical Details

← Older revision		Revision as of 08:44, 20 February 2009
Line 15:		Line 15:
	\|Where Used:		\|Where Used:
	\|[[Component Element (Data)\|Components]], [[Thing Element (Data)\|Things]]		\|[[Component Element (Data)\|Components]], [[Thing Element (Data)\|Things]]
			\|-
			\|Procedure Use:
			\|"evalrule" type, "pick" context
	\|-		\|-
	\|}		\|}

Rob at 00:08, 16 December 2008

2008-12-16T00:08:20Z

← Older revision		Revision as of 00:08, 16 December 2008
Line 12:		Line 12:
	\|Fields Finalized?		\|Fields Finalized?
	\|No		\|No
			\|-
			\|Where Used:
			\|[[Component Element (Data)\|Components]], [[Thing Element (Data)\|Things]]
	\|-		\|-
	\|}		\|}

Rob at 12:21, 15 December 2008

2008-12-15T12:21:40Z

← Older revision		Revision as of 12:21, 15 December 2008
Line 19:		Line 19:
	:{\| class="infotable"		:{\| class="infotable"
	\|class="leftnormal"\|valid		\|class="leftnormal"\|valid
	\|Entry: Assumed the rule is '''not''' satisfied with a value of zero.<br>		\|(Number) Entry: Assumed the rule is '''not''' satisfied with a value of zero.<br>
	Exit: Indicates whether the rule is satisfied (non-zero) or not satisfied (zero).		Exit: Indicates whether the rule is satisfied (non-zero) or not satisfied (zero).
	\|-		\|-
	\|message		\|message
	\|Entry: Contains the default message text if the rule is not satisfied.<br>		\|(String) Entry: Contains the default message text if the rule is not satisfied.<br>
	Exit: Contains the final message text to display if the rule is not satisfied. The text may contain [[Encoded Text\|encoding]].		Exit: Contains the final message text to display if the rule is not satisfied. The text may contain [[Encoded Text\|encoding]].
	\|-		\|-
	\|summary		\|summary
	\|Entry: Contains the default summary text if the rule is not satisfied.<br>		\|(String) Entry: Contains the default summary text if the rule is not satisfied.<br>
	Exit: Contains the final summary text to display if the rule is not satisfied.		Exit: Contains the final summary text to display if the rule is not satisfied.
	\|-		\|-

Rob at 12:12, 15 December 2008

2008-12-15T12:12:22Z

← Older revision		Revision as of 12:12, 15 December 2008
Line 24:		Line 24:
	\|message		\|message
	\|Entry: Contains the default message text if the rule is not satisfied.<br>		\|Entry: Contains the default message text if the rule is not satisfied.<br>
	Exit: Contains the final message text to display if the rule is not satisfied.		Exit: Contains the final message text to display if the rule is not satisfied. The text may contain [[Encoded Text\|encoding]].
	\|-		\|-
	\|summary		\|summary

Rob at 09:47, 14 December 2008

2008-12-14T09:47:02Z

← Older revision		Revision as of 09:47, 14 December 2008
Line 34:		Line 34:
	==Description==		==Description==

	The EvalRule script is very similar to an [[Eval Script\|Eval script]], with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.		The EvalRule script is very similar to an [[Eval Script\|Eval script]], with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points, in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.

	An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated. The rule can be anything you want. However, the rule is always either satisfied or not satisfied. This is determined by the "valid" special symbol. The symbol starts out as zero, indicating that the rule is not satisfied. At any point during the script, you can set the symbol to non-zero, thereby indicating that the rule '''is''' satisfied. You can also change the symbol value throughout the script if you want. The only value that matters is the final value when the script ends, where a non-zero value indicates the ~~script~~ is satisfied.		An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated. The rule can be anything you want. However, the rule is always either satisfied or not satisfied. This is determined by the "valid" special symbol. The symbol starts out as zero, indicating that the rule is not satisfied. At any point during the script, you can set the symbol to non-zero, thereby indicating that the rule '''is''' satisfied. You can also change the symbol value throughout the script if you want. The only value that matters is the final value when the script ends, where a non-zero value indicates the rule is satisfied.

	If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When ~~this~~ situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.		If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When these situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.

	Since an EvalRule script is equivalent to an Eval script, it '''is''' possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.		Since an EvalRule script is equivalent to an Eval script, it '''is''' possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.

	Like an Eval script, every EvalRule script is associated with a particular thing. If an EvalRule script is defined for component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every EvalRule script for that thing are created and managed by HL. You associate all of the validation rules with each pick via the EvalRule scripts defined for the underlying thing.		Like an Eval script, every EvalRule script is associated with a particular thing. If an EvalRule script is defined for a component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every EvalRule script for that thing are created and managed by HL. You associate all of the validation rules with each pick via the EvalRule scripts defined for the underlying thing.

	When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and test the state of anything that impacts the rule. However, a given EvalRule script should ~~will~~ typically either pertain to the associated pick or pertain to the actor as a whole.		When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and test the state of anything that impacts the rule. However, a given EvalRule script should typically either pertain to the associated pick or pertain to the actor as a whole.

	==Example==		==Example==

Rob at 09:25, 14 December 2008

2008-12-14T09:25:08Z

← Older revision		Revision as of 09:25, 14 December 2008
Line 36:		Line 36:
	The EvalRule script is very similar to an [[Eval Script\|Eval script]], with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.		The EvalRule script is very similar to an [[Eval Script\|Eval script]], with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.

	An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated.		An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated. The rule can be anything you want. However, the rule is always either satisfied or not satisfied. This is determined by the "valid" special symbol. The symbol starts out as zero, indicating that the rule is not satisfied. At any point during the script, you can set the symbol to non-zero, thereby indicating that the rule '''is''' satisfied. You can also change the symbol value throughout the script if you want. The only value that matters is the final value when the script ends, where a non-zero value indicates the script is satisfied.


	If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When this situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.		If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When this situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.
Line 43:		Line 42:
	Since an EvalRule script is equivalent to an Eval script, it '''is''' possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.		Since an EvalRule script is equivalent to an Eval script, it '''is''' possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.

			Like an Eval script, every EvalRule script is associated with a particular thing. If an EvalRule script is defined for component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every EvalRule script for that thing are created and managed by HL. You associate all of the validation rules with each pick via the EvalRule scripts defined for the underlying thing.

			When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and test the state of anything that impacts the rule. However, a given EvalRule script should will typically either pertain to the associated pick or pertain to the actor as a whole.
	the primary workhorse throughout any set of data files. This script is scheduled within the evaluation cycle and where you will orchestrate the virtually all of the effects for the game system. If a special ability confers a bonus to certain skills, you'll use an Eval script to apply them. If attributes confer adjustments to abilities, attacks, damage, or anything else, you'll use Eval scripts to apply them. Calculated abilities, such as attack ratings or casting powers will be determined through Eval scripts. The list is endless.

	Every Eval script is associated with a particular thing. If an Eval script is defined for component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every Eval script for that thing are created and managed by HL. You associate all of the primary behaviors with each pick via the Eval scripts defined for the underlying thing.

	When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and ~~effect changes anywhere you deem appropriate~~. However, ~~all of the changes~~ will typically either ~~be made~~ to the associated pick or ~~be made~~ to ~~other objects based on facets of~~ the ~~associated pick.~~

	As a general rule, all of the dynamic effects that are applied throughout your data files should be handled via Eval scripts. Because the timing of all Eval scripts is controlled, you can ensure that all of the different effects of different scripts are applied in a ~~carefully defined sequence. For example, in the d20 System, adjustments to attributes (e.g. from magic items) must be applied before the bonuses conferred by attributes are calculated and applied.~~

	Eval scripts provide a single, generalized mechanism through which you can accomplish just about anything. As a result, the actual behaviors of an Eval script will vary more widely than with any other type of script. If there is one type of script to get comfortable with first, it is definitely the Eval script.

	==Example==		==Example==

	~~Due to the wide range of behaviors that~~ can be ~~applied via Eval scripts, there is no one good example~~. ~~The XML below shows three separate Eval scripts that are defined as part of the basic handling of equipment within~~ the Sample data files~~. Each script~~ is ~~scheduled~~ to ~~be performed at~~ a ~~different time during the overall evaluation cycle, with the timing ensuring that each behavior is properly interleaved with other behaviors triggered by other objects~~.		An EvalRule script can be used to test virtually anything. Within the Sample data files, a rule is used to ensure that pieces of gear are not both equipped and held within a container (e.g. a sword being equipped and stored in a backpack). The rule below will verify this condition.

	<pre>		<pre>
	~~<!-- All melee weapons get the appropriate tag -->~~		~if not both equipped and held within a container, we're valid
	~~<eval index="1" phase="Setup" priority="5000"><![CDATA[~~		if (field[grIsEquip].value + isgearheld < 2) then
	~~perform assign[Armory.Melee]~~		@valid = 1
	~~]]></eval>~~		done
			endif
	~~<!-- Calculate the net attack roll for the weapon -->~~
	~~<eval index="2" phase="Final" priority="7000" name="Calc wpNetAtk"><![CDATA[~~
	field[~~wpNetAtk~~].value ~~= #trait[skMelee]~~ + ~~field[wpBonus].value + field[wpPenalty].value~~
	~~]]></eval>~~

	~~<!-- Prepend any derived special notes to the appropriate field -->~~
	~~<eval index~~=~~"3" phase="Render" priority="2000"><![CDATA[~~
	~~var special as string~~

	~~~assign any appropriate special notes to the "special" variable here~~

	~~~prepend any existing special details with~~ the ~~notes for this weapon~~		~mark the tab as invalid
	~~if (empty(special)~~ = 0~~) then~~		linkvalid = 0
	~~if (field[wpNotes].isempty = 0) then~~
	~~special &= ", "~~
	~~endif~~
	~~field[wpNotes].text = special & field[wpNotes].text~~
	~~endif~~
	~~]]></eval>~~
	</pre>		</pre>

Rob: New page: {{context|Kit Reference|Script Types}} ==Technical Details== :{| class="scripttable" |class="leftnormal"|Initial Context: |Pick |- |Alternate Context: |None |- |Fields F...

2008-12-14T09:15:21Z

New page: {{context|Kit Reference|Script Types}} ==Technical Details== :{| class="scripttable" |class="leftnormal"|Initial Context: |Pick |- |Alternate Context: |None |- |Fields F...

New page

{{context|Kit Reference|Script Types}}

==Technical Details==

:{| class="scripttable"
|class="leftnormal"|Initial Context:
|[[Pick Context|Pick]]
|-
|Alternate Context:
|None
|-
|Fields Finalized?
|No
|-
|}

The EvalRule script utilizes the following special symbols:

:{| class="infotable"
|class="leftnormal"|valid
|Entry: Assumed the rule is '''not''' satisfied with a value of zero.<br>
Exit: Indicates whether the rule is satisfied (non-zero) or not satisfied (zero).
|-
|message
|Entry: Contains the default message text if the rule is not satisfied.<br>
Exit: Contains the final message text to display if the rule is not satisfied.
|-
|summary
|Entry: Contains the default summary text if the rule is not satisfied.<br>
Exit: Contains the final summary text to display if the rule is not satisfied.
|-
|}

==Description==

The EvalRule script is very similar to an [[Eval Script|Eval script]], with the primary distinction being that the EvalRule script verifies a rule is observed instead of applying changes. This script is scheduled during the evaluation cycle, so it allows you to check the state of an actor at intermediate points in addition to at the end of evaluation. Intermediate checks make it possible to verify values before they are further modified by other aspects of the character.

An EvalRule script shares all the same behaviors of an Eval script, plus it adds the rule to be validated.

If the validation test is not satisfied, the message and summary for the rule are displayed within the validation report and validation summary for the actor, respectively. Since the message and summary are typically static requirements (e.g. an attribute must be a value of X or more), you will rarely need to modify them. However, there will be cases where you want to tailor the message and/or summary to provide more detailed information based on dynamic information. When this situations arise, simply set the "message" and/or "summary" special values to the desired contents and they will be used.

Since an EvalRule script is equivalent to an Eval script, it '''is''' possible to apply changes throughout the structural hierarchy via the script. However, it is generally a bad idea to do that, since the purpose of an EvalRule script is to validate a rule - not effect change. We therefore recommend that you avoid applying changes within EvalRule scripts.

the primary workhorse throughout any set of data files. This script is scheduled within the evaluation cycle and where you will orchestrate the virtually all of the effects for the game system. If a special ability confers a bonus to certain skills, you'll use an Eval script to apply them. If attributes confer adjustments to abilities, attacks, damage, or anything else, you'll use Eval scripts to apply them. Calculated abilities, such as attack ratings or casting powers will be determined through Eval scripts. The list is endless.

Every Eval script is associated with a particular thing. If an Eval script is defined for component, then it is inherited by the things which derive from that component. When a thing is added to a container, it becomes a pick, and new instances of every Eval script for that thing are created and managed by HL. You associate all of the primary behaviors with each pick via the Eval scripts defined for the underlying thing.

When invoked, an Eval script starts with its associated pick as its initial context. You are free to navigate through the hierarchy and effect changes anywhere you deem appropriate. However, all of the changes will typically either be made to the associated pick or be made to other objects based on facets of the associated pick.

As a general rule, all of the dynamic effects that are applied throughout your data files should be handled via Eval scripts. Because the timing of all Eval scripts is controlled, you can ensure that all of the different effects of different scripts are applied in a carefully defined sequence. For example, in the d20 System, adjustments to attributes (e.g. from magic items) must be applied before the bonuses conferred by attributes are calculated and applied.

Eval scripts provide a single, generalized mechanism through which you can accomplish just about anything. As a result, the actual behaviors of an Eval script will vary more widely than with any other type of script. If there is one type of script to get comfortable with first, it is definitely the Eval script.

==Example==

Due to the wide range of behaviors that can be applied via Eval scripts, there is no one good example. The XML below shows three separate Eval scripts that are defined as part of the basic handling of equipment within the Sample data files. Each script is scheduled to be performed at a different time during the overall evaluation cycle, with the timing ensuring that each behavior is properly interleaved with other behaviors triggered by other objects.

<pre>

<eval index="1" phase="Setup" priority="5000"><![CDATA[
perform assign[Armory.Melee]
]]></eval>


<eval index="2" phase="Final" priority="7000" name="Calc wpNetAtk"><![CDATA[
field[wpNetAtk].value = #trait[skMelee] + field[wpBonus].value + field[wpPenalty].value
]]></eval>


<eval index="3" phase="Render" priority="2000"><![CDATA[
var special as string

~assign any appropriate special notes to the "special" variable here

~prepend any existing special details with the notes for this weapon
if (empty(special) = 0) then
if (field[wpNotes].isempty = 0) then
special &= ", "
endif
field[wpNotes].text = special & field[wpNotes].text
endif
]]></eval>
</pre>