Templates explanation - Revision history

Tinkerer: Mention script naming convention for local instances

2017-10-13T09:01:14Z

Mention script naming convention for local instances

← Older revision		Revision as of 09:01, 13 October 2017
Line 22:		Line 22:
	<p>A local instance can live without data. It '''just refers''' to the root and it will get its data there.<br>		<p>A local instance can live without data. It '''just refers''' to the root and it will get its data there.<br>
	However, if the root is deleted, the link is broken and the local instance will no longer be able to show anything. (This is why you get errors if roots are deleted and they’re used by local instances.)</p>		However, if the root is deleted, the link is broken and the local instance will no longer be able to show anything. (This is why you get errors if roots are deleted and they’re used by local instances.)</p>

			{{warning\|If you place a local instance that will be referenced from any script, or that should be assigned as a parameter to a script, a skill, or any action in the sidebar, make sure its name starts with '''S_'''. This tells the editor the object is/will be referenced, and adds it to auto-completion lists in script editors and to selection menus elsewhere.}}

	<br />		<br />

Kevin: Protected "Templates explanation" ([Edit=⧼protect-level-larianeditonly⧽] (indefinite) [Move=⧼protect-level-larianeditonly⧽] (indefinite))

2017-10-02T11:35:50Z

Protected "Templates explanation" ([Edit=⧼protect-level-larianeditonly⧽] (indefinite) [Move=⧼protect-level-larianeditonly⧽] (indefinite))

← Older revision	Revision as of 11:35, 2 October 2017
(No difference)

Tinkerer: Explain what an inspector is

2017-09-13T15:43:05Z

Explain what an inspector is

← Older revision		Revision as of 15:43, 13 September 2017
Line 157:		Line 157:
	* '''Alignment:''' for specifying for instance more regional alignments to NPCs		* '''Alignment:''' for specifying for instance more regional alignments to NPCs
	* '''IsBoss:''' for specifying that this particular local is a boss character		* '''IsBoss:''' for specifying that this particular local is a boss character
	* '''IsInspector:''' if you want to turn specific items or characters that are usually not inspectors into an inspector		* '''IsInspector:''' if you want to turn specific items or characters that are usually not inspectors into an inspector
			** Inspectors are items that [[Osiris/API/SetCanJoinCombat\|join combat]] and participate in the turn order, but that do not keep the combat alive (i.e., if the only "enemies" left are all inspectors, combat will end)
	** A trap item should have this on root level, or you will find yourself turning this on constantly for all trap locals		** A trap item should have this on root level, or you will find yourself turning this on constantly for all trap locals
	** Other than traps, this may be necessary on some locals in some circumstances		** Other than traps, this may be necessary on some locals in some circumstances

Kevin: /* Overrides on local instances */

2017-08-02T14:22:21Z

Overrides on local instances

← Older revision		Revision as of 14:22, 2 August 2017
Line 119:		Line 119:
	<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>		<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>

	~~<div>~~		[[File:Ingamearmy.jpg\|frame\|none\|This very specific ArmyMan01 must always be green no matter what colour ArmyMan Root has. ArmyMan01 is really special.” In this case, we can override the colour property with green. The rest of the properties are still automatically inherited.]]
	[[File:Ingamearmy.jpg\|frame\|none]]
	~~</div>~~
	~~<sub>~~This very specific ArmyMan01 must always be green no matter what colour ArmyMan Root has. ArmyMan01 is really special.” In this case, we can override the colour property with green. The rest of the properties are still automatically inherited.~~</sub>~~

Kevin: /* Overrides on local instances */

2017-08-02T14:22:03Z

Overrides on local instances

← Older revision		Revision as of 14:22, 2 August 2017
Line 119:		Line 119:
	<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>		<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>

	[[File:Ingamearmy.jpg\|frame\|none~~\|“This~~ very specific ArmyMan01 must always be green no matter what colour ArmyMan Root has. ArmyMan01 is really special.” In this case, we can override the colour property with green. The rest of the properties are still automatically inherited.]]		<div>
			[[File:Ingamearmy.jpg\|frame\|none]]
			</div>
			<sub>This very specific ArmyMan01 must always be green no matter what colour ArmyMan Root has. ArmyMan01 is really special.” In this case, we can override the colour property with green. The rest of the properties are still automatically inherited.</sub>


	<p>But one must always be careful, because overriding properties can be a cause of bugs too.</p>		<p>But one must always be careful, because overriding properties can be a cause of bugs too.</p>
Line 137:		Line 141:

	<br />		<br />

	= Overrides mean: no more updates from root =		= Overrides mean: no more updates from root =
	<p>However, as a designer or artist, you must know that '''a property of a local that gets an override no longer inherits from its root'''.<br>		<p>However, as a designer or artist, you must know that '''a property of a local that gets an override no longer inherits from its root'''.<br>

Kevin at 14:10, 2 August 2017

2017-08-02T14:10:09Z

← Older revision		Revision as of 14:10, 2 August 2017
Line 11:		Line 11:
	[[File:Rootsarmy.jpg\|frame\|Army Men game has 2 roots: ArmyMan and Tank. Thanks art team!\|none]]		[[File:Rootsarmy.jpg\|frame\|Army Men game has 2 roots: ArmyMan and Tank. Thanks art team!\|none]]

			<br />
	= Local instances/templates =		= Local instances/templates =
	<p>You never really place a root in the game. You place a '''reference''' to the root in the game.<br>		<p>You never really place a root in the game. You place a '''reference''' to the root in the game.<br>
Line 22:		Line 23:
	However, if the root is deleted, the link is broken and the local instance will no longer be able to show anything. (This is why you get errors if roots are deleted and they’re used by local instances.)</p>		However, if the root is deleted, the link is broken and the local instance will no longer be able to show anything. (This is why you get errors if roots are deleted and they’re used by local instances.)</p>

			<br />
	= Inheritance =		= Inheritance =
	<p>If you are an artist, think of a root template as a '''magical mold''' or a magical pattern: when you update the mold, everything you ever made with it updates too!<br>		<p>If you are an artist, think of a root template as a '''magical mold''' or a magical pattern: when you update the mold, everything you ever made with it updates too!<br>
Line 48:		Line 50:
	\|}		\|}

			<br />
	= Consistency and player expectations =		= Consistency and player expectations =
	By using roots, we also ensure consistent behaviour of the items in our world.		By using roots, we also ensure consistent behaviour of the items in our world.
Line 87:		Line 90:
	<p>To live up to these expectations, we '''set up the roots correctly''', and as a result, all its instances inherit the settings and everything works as it should. If one item in the game behaves differently, it is experienced as a bug and it’s not the way this game was designed.</p>		<p>To live up to these expectations, we '''set up the roots correctly''', and as a result, all its instances inherit the settings and everything works as it should. If one item in the game behaves differently, it is experienced as a bug and it’s not the way this game was designed.</p>

			<br />
	= What is wrong =		= What is wrong =
	<p>If you turn off or change this expected, standard behaviour on a local instance, that is wrong in 99% of the cases: it is no longer consistent with the other items of this type and confuses the player. It’s a bug, it’s an inconsistency.</p>		<p>If you turn off or change this expected, standard behaviour on a local instance, that is wrong in 99% of the cases: it is no longer consistent with the other items of this type and confuses the player. It’s a bug, it’s an inconsistency.</p>
Line 111:		Line 115:
	\|}		\|}

			<br />
	= Overrides on local instances =		= Overrides on local instances =
	<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>		<p>A designer or an artist building the world '''can''' override properties of game objects. Because '''sometimes''', there are '''exceptions''' and then overriding a property is a powerful tool.</p>
Line 131:		Line 136:
	And as soon as you find yourself doing the same thing over and over again to the same locals, think about what you’re doing.</p>		And as soon as you find yourself doing the same thing over and over again to the same locals, think about what you’re doing.</p>

			<br />
	= Overrides mean: no more updates from root =		= Overrides mean: no more updates from root =
	<p>However, as a designer or artist, you must know that '''a property of a local that gets an override no longer inherits from its root'''.<br>		<p>However, as a designer or artist, you must know that '''a property of a local that gets an override no longer inherits from its root'''.<br>
Line 137:		Line 143:
	[[File:Purplearmy.jpg\|frame\|none\|“Red is out, we should make our ArmyMan purple in the entire game. For Prince!” We set the root’s colour property with purple. However, all instances that have an override on colour do not inherit this, and that may be fine if that’s what you wanted.]]		[[File:Purplearmy.jpg\|frame\|none\|“Red is out, we should make our ArmyMan purple in the entire game. For Prince!” We set the root’s colour property with purple. However, all instances that have an override on colour do not inherit this, and that may be fine if that’s what you wanted.]]

			<br />
	= Perfectly normal overrides =		= Perfectly normal overrides =
	<p>There are cases in which it can be perfectly normal to use the override functionality.<br>		<p>There are cases in which it can be perfectly normal to use the override functionality.<br>
Line 177:		Line 184:
	* '''Skills:''' a local can have different skills than its root		* '''Skills:''' a local can have different skills than its root

			<br />
	= The parable of the 3 designers =		= The parable of the 3 designers =
	<p>3 designers each made a farm.<br>		<p>3 designers each made a farm.<br>
Line 197:		Line 205:
	<p>The game is now illegal in Australia.</p>		<p>The game is now illegal in Australia.</p>

			<br />
	= Why changing locals is not “a quick hack” =		= Why changing locals is not “a quick hack” =
	<p>The argument is often made that to quickly fix something or hack something, or get something ready quick, you “do it to the local”.</p>		<p>The argument is often made that to quickly fix something or hack something, or get something ready quick, you “do it to the local”.</p>
Line 217:		Line 226:
	* Causing skeletons that drop out of the closet at the end of the project and wasting time that could have been spent on polish instead of fixing “quick” hacks		* Causing skeletons that drop out of the closet at the end of the project and wasting time that could have been spent on polish instead of fixing “quick” hacks

			<br />
	= Real life examples of what people did wrong and why it was wrong =		= Real life examples of what people did wrong and why it was wrong =
	=== The jar story ===		=== The jar story ===
Line 247:		Line 257:
	\|}		\|}

			<br />
	=== The book story ===		=== The book story ===
	<p>You have a library full of books. You think there are too many books there, and too many of them don’t have actual content.</p>		<p>You have a library full of books. You think there are too many books there, and too many of them don’t have actual content.</p>
Line 271:		Line 282:
	\|}		\|}

			<br />
	=== The small statuette story ===		=== The small statuette story ===
	<p>Your job is to decorate the museum.<br>		<p>Your job is to decorate the museum.<br>
Line 303:		Line 315:
	\|}		\|}

			<br />
	=== The story about you don’t want to break other people’s stuff ===		=== The story about you don’t want to break other people’s stuff ===
	<p>You notice that a book cannot be picked up.<br>		<p>You notice that a book cannot be picked up.<br>

LarSeb at 12:59, 1 August 2017

2017-08-01T12:59:47Z

@@ Line 301: / Line 301: @@
 <p>If the root of this statue would get a certain update (for instance, all these statues are now a waypoint shrine),<br>
 your statue will inherit behaviour it was not intended to inherit.</p>
 |}

LarSeb at 12:57, 1 August 2017

2017-08-01T12:57:56Z

← Older revision		Revision as of 12:57, 1 August 2017
Line 218:		Line 218:

	= Real life examples of what people did wrong and why it was wrong =		= Real life examples of what people did wrong and why it was wrong =
			=== The jar story ===
			<p>You get a ticket about the name of a jar being wrong. There is nothing special about the jar. It is not a quest item or puzzle item.</p>

			{\| class="wikitable"
			\|-
			\| '''Correct''' \|\| '''Wrong'''
			\|-
			\| You look for the root template of the jar and you fix the name of the root. \|\| You go to the location of the jar in the ticket.<br>You fix the name of the local.
			\|-
			\| '''Why correct?''' \|\| '''Why wrong?'''
			\|-
			\|
			<p>You just fixed not just this one jar, but all 473 jars in one go.<br>
			Future jars will also have the correct name</p>
			\|\|
			<p>You fixed only 1 instance of the jar. There are 472 other jars.</p>
			<p>You could fix all 472 other jars if you have a lot of time. But you don’t.</p>
			<p>Even if you did fix all 472 jars, 23 of them are checked out by someone else and 34 are being added at this moment and 78 will be added between now and next year. How will you fix those?</p>
			<p>When the name of the root gets fixed or updated, your jar name remains in the game and you have made a unique jar.<br>
			It will not stack with other jars. It will stand out and the player will think it is special.</p>
			\|}

			{\| class="wikitable"
			\|-
			\|
			<p>“I was told to unstub the name of these jars.” Yes. But not these particular jars, you are taking it too literally.<br>
			You were told to unstub all jars of this type in the entire game. So you do it in the root.</p>
			\|}

			=== The book story ===
			<p>You have a library full of books. You think there are too many books there, and too many of them don’t have actual content.</p>

			{\| class="wikitable"
			\|-
			\| '''Correct''' \|\| '''Wrong'''
			\|-
			\|
			<p>You leave the books be and use a generic BookID<br>
			(e.g. “You cannot read this.” or “Pages are ripped from this book so it doesn’t make a lot of sense anymore.”)</p>
			<p>Also correct: you remove some books (careful not to touch story items) and use BookRows instead.</p>
			\|\|
			<p>You delete their onUse action.</p>
			<p>And you don’t want to waste the player’s time, so you turn off the flags “CanMove” and “CanPickup”.<br>
			You think they’re only decoration.</p>
			\|-
			\| '''Why correct?''' \|\| '''Why wrong?'''
			\|-
			\| You are keeping the game consistent.
			\|\|
			<p>Killing player expectation: you should never make a moveable item non-moveable.</p>
			<p>Killing player expectation: you should never make an interactable item non-interactable.</p>
			\|}

			=== The small statuette story ===
			<p>Your job is to decorate the museum.<br>
			You think you’re short on decoration items so you decide to start using those big statues that are all over the game.</p>

			{\| class="wikitable"
			\|-
			\| '''Correct''' \|\| '''Wrong'''
			\|-
			\|
			<p>You select the root of a statue, right click it, you choose “Create new from selected…” and you make a new root.<br>
			You give it the same name but append _Tiny</p>
			<p>You set the Scaling of the new root to 5%.</p>
			<p>Yet grab your new root and put it on a shelf.</p>
			<p>You tell a lead you made a new root and that it needs checking (stats, flags, visual, AI bounds…).</p>
			\|\|
			You grab a statue and put it on a shelf, you resize it to 5% and check it in thinking “I’m done, I am so smart.”
			\|-
			\| '''Why correct?''' \|\| '''Why wrong?'''
			\|-
			\|
			<p>All people responsible will now update your root.<br>
			Doing so will result in all current and future instances of the little statue to be correct.</p>
			<p>They will all get stats, moveable and pickupable flags, AI bounds, and a visual made for that small size.</p>
			\|\|
			<p>The statue can not be moved or picked up. There is no specific root for this statue, so nobody will ever know.<br>
			You could start overriding this local, but then you are creating a very specific statue.<br>
			If someone else is doing the same thing in another spot in the game, you are both creating inconsistency.<br>
			By doing it to a local, you are hiding the problem.</p>
			<p>If the root of this statue would get a certain update (for instance, all these statues are now a waypoint shrine),<br>
			your statue will inherit behaviour it was not intended to inherit.</p>
			\|}

LarSeb at 12:44, 1 August 2017

2017-08-01T12:44:20Z

← Older revision		Revision as of 12:44, 1 August 2017
Line 127:		Line 127:
	\|-		\|-
	\|}		\|}

			<p>Sometimes, overrides on local instances are perfectly possible and encouraged. But as soon as you are changing systemics, think about what you’re doing.<br>
			And as soon as you find yourself doing the same thing over and over again to the same locals, think about what you’re doing.</p>

			= Overrides mean: no more updates from root =
			<p>However, as a designer or artist, you must know that '''a property of a local that gets an override no longer inherits from its root'''.<br>
			This is only logical, because it is an override. Even if the root is updated, the local instance’s property is still overridden.</p>

			[[File:Purplearmy.jpg\|frame\|none\|“Red is out, we should make our ArmyMan purple in the entire game. For Prince!” We set the root’s colour property with purple. However, all instances that have an override on colour do not inherit this, and that may be fine if that’s what you wanted.]]

			= Perfectly normal overrides =
			<p>There are cases in which it can be perfectly normal to use the override functionality.<br>
			The following properties can be overridden '''in the following cases''':</p>

			* '''DisplayName:''' if you want to give this particular local a specific name.
			** Pitfall: if you find yourself selecting and renaming an entire group of similar item locals or character locals, you probably want to:
			*:: a) fix the root’s name
			*:: b) create a new root
			** ...because you are probably creating a certain new type that warrants a root
			* '''Alignment:''' for specifying for instance more regional alignments to NPCs
			* '''IsBoss:''' for specifying that this particular local is a boss character
			* '''IsInspector:''' if you want to turn specific items or characters that are usually not inspectors into an inspector
			** A trap item should have this on root level, or you will find yourself turning this on constantly for all trap locals
			** Other than traps, this may be necessary on some locals in some circumstances
			* '''ActivationGroupId:''' If you want to group locals to start together (this is never set on root because it is so local-specific)
			* '''Amount:''' if you want to put an item in the world and make it a stack
			** e.g. gold or arrows
			** it also works on potato but the visual doesn’t change
			* '''Description:''' if you want to give this particular local a specific description.
			** Pitfall: example. You see a healing potion in the game. It has no description. You click on the local instance of the potion and you fill in the description.<br>This is '''wrong'''. You are only making a description for that one particular healing potion. If you want all healing potions in the game to have that description, you must fix the root.<br>If you fill in a description in the root, all healing potions in the game will have the description. Use this field only to override an existing root description for a particular and specific local.
			** Pitfall: example. You see a painting in the game. It has no description. You click on seven local instances of the painting and you fill in the description.<br>This is '''wrong'''. Someone somewhere else uses the same painting root. This will not have the description you filled in because you didn’t fill it in on the root.<br>Someone else fills in a proper description on the root. Your seven instances will not inherit it because you made the error of filling in a description on the local instances.
			* '''Icon:''' if you have a really specific icon for this particular local version (e.g. because it is a special NPC or a unique item)
			* '''Treasure / Inventory:''' if you want to give this particular instance of the item or character a specific treasure table
			** Pitfall: if you find yourself doing this to the local because the root has no treasure filled in, are you sure the root doesn’t need a default treasure?
			* '''Trade Treasure :''' if you want to give this particular copy of the character a specific trade table
			* '''Items:''' usually not set on a root, this enables you to put things in an item or in a character’s pockets
			* '''LevelOverride:''' can be set to a specific level, zero to take level of stats, or -1 to take level trigger
			* '''LockLevel:''' to change lockpicking requirements for this specific container
			* '''Stats:''' to change to more specific stats (more common override for characters and weapons and armour, most other items only get an override for special cases like quest objects;<br>remember that item combos might not work if you change stats)
			* '''StoryItem:''' check this flag if this is a story item
			* '''TreasureLevel:''' set to a specific level to force a level, zero to get from area, -1 to get from level trigger
			* '''UsePartyLevelForTreasureLevel:''' check this box if you want the party level to determine the level of treasure this particular container generates
			* '''OnUseActions:''' for story scripting purposes, this can trigger extra uses, but its default uses should be taken into account carefully;<br>the designer should take into account that the default scripts on the root may often change or get fixed and that an override will then not be inherited as soon as this part is changed, so use with caution and don’t forget about player expectation
			* '''Scale:''' don’t exaggerate with scaling. This means: don’t turn a ten foot statue into a six inch figurine. And don’t scale a needle up to a sword.
			* '''Tags:''' sometimes, a local’s tags can change
			* '''VisualSet:''' data can be changed
			* '''Equipment:''' a local can wear different weapons than its root
			* '''IsHardcoreOnly:''' a local can be added for HC only
			* '''Skills:''' a local can have different skills than its root

			= The parable of the 3 designers =
			<p>3 designers each made a farm.<br>
			When inspecting, the lead designer says to all 3 of them: “I want to see a rooster here among the chickens.”</p>

			* Designer 1 clicks one local chicken, changes the name to “Rooster” and calls it a day.
			* Designer 2 clicks a local chicken, changes the name to “Cock”, sets the treasure to Empty, sets the stats to FTJ_Magister_Soldier cause he thinks it should be stronger than a chicken, and requests an icon and a visual for a cock.
			* Designer 3 opens his Roots panel, right-clicks the root ANIMAL_Chicken and selects “Create new from selected…” and gives it the name “ANIMAL_Rooster”.<br>He gives the root a displayname, sets the treasure to Empty, and puts one instance of the root ANIMAL_Rooster near his chickens and requests an icon and a visual for a rooster.

			<p>There are now 3 different roosters in the game.</p>

			<p>The third designer’s root gets filled in by art, sound designers made it cock-a-doodle, and someone makes a treasure for the rooster and specific stats.<br>
			The combat designer changes the behaviour of the root of the rooster: it doesn’t flee but has powerful attacks with its claws and beak.</p>

			<p>Everyone’s forgotten about the local overrides. Designer 1’s rooster is still laying eggs if you kill it and is now just a white chicken called “Rooster”.</p>

			<p>Designer 2’s rooster never got the icon or the visual, cause the art department thinks they filled his request by completing the root.<br>
			Designer 2’s “cock” is also being mistranslated by a lot of loca companies and it’s taken hours to figure out where the dirty word is coming from cause the root has the name “Rooster”.</p>

			<p>The game is now illegal in Australia.</p>

			= Why changing locals is not “a quick hack” =
			<p>The argument is often made that to quickly fix something or hack something, or get something ready quick, you “do it to the local”.</p>

			<p>This is wrong in a lot of cases.</p>

			<p>First and foremost, creating a new root for your specific item is only 2 clicks away.</p>

			<p>Second of all, if you are trying to fix a local while you should have fixed the root,<br>
			you went through more trouble loading the level and finding the local, than fixing the root, which would have been the correct solution.</p>

			Third, by “hacking the local”, you are
			* Creating unexpected behaviour
			* Creating inconsistent behaviour
			* Possibly removing expected behaviour
			* Possibly no longer inheriting future updates and fixes to the root
			* Not updating the other locals that may need the same treatment you are giving this local (you should be doing it in the root)
			* Possibly creating a standalone version of something that is now untraceable (needs an icon but it’s hiding away between thousands of other tiny local items)
			* Causing bugs that are hard to find and fix because “the root works”
			* Causing skeletons that drop out of the closet at the end of the project and wasting time that could have been spent on polish instead of fixing “quick” hacks

			= Real life examples of what people did wrong and why it was wrong =

LarSeb at 12:23, 1 August 2017

2017-08-01T12:23:07Z

Show changes