View source for Talk:Entity Article Template

=Major changes coming. Speak now, or forever hold your peace.=
Large changes have been in discussion for all entity pages. As this will affect info for all games, we're hoping to get input from far and wide.
#Combine the "Entity Description" sections into the headers. There's no reason for pages to have a table of contents right in the middle of sentences that give basic information about entities.
#Add non-SmartEdit versions of keyvalues next to their SmartEdit names. This may or may not include changes to [[Template:KV]].
#Slight changes to how dedicated console commands & variables are done. Text like "int" should instead give short descriptions of what the variable/parameter is, like "hammer units". (see [[npc_blob]] for what I'm thinking they should look like).
#Change the set of templates such as [[Template:KV Targetname]] so that they will by default display HL2-only information, and will have modifiers for adding on values etc that were added in later versions of source. This is because pages for entities ''exclusive'' to older games (especially Half-Life 2) have tons of information that doesn't apply to them on their pages such as the <code>RunScriptFile</code> input.
:::I also noticed this is true for all `trigger` entities; they all warn that, in CS:S, parenting of these entities may break the map. However, many of these entities are not in CS:S. --[[User:Stract|Stract]] ([[User talk:Stract|talk]]) 20:50, 6 July 2018 (UTC)

The main reason for the fuss is number 4. The moment templates begin to be altered, they will immediately look wrong for a large number of pages. This is probably unavoidable, but this won't be a huge problem if we coordinate.

Voice your concerns below. Discussion about these issues is also being held in [https://discord.gg/QV9T74W this Discord server] [[User:Pinsplash|Pinsplash]] ([[User talk:Pinsplash|talk]]) 10:54, 4 July 2018 (UTC)

Bumping this again since people are coming back onto the wiki now. [[User:Pinsplash|Pinsplash]] ([[User talk:Pinsplash|talk]]) 19:59, 6 July 2018 (UTC)

:For the "global" entity keyvalues (targetname etc), it might be best to actually mirror the entity class hierachy (`BaseEntityAnimating`, `BaseEntity`), etc. I actually do have a library which can parse FGD information into whatever you like. --[[User:TeamSpen210|TeamSpen210]] ([[User talk:TeamSpen210|talk]]) 11:16, 4 July 2018 (UTC)

:Good news, I think I've figured out how to do #4 without disrupting hundreds of other pages! [[User:Pinsplash|Pinsplash]] ([[User talk:Pinsplash|talk]]) 12:46, 7 July 2018 (UTC)

:Well, I think the work on templates is mostly done now. Think it's time to start putting them on pages. [[User:Pinsplash|Pinsplash]] ''([[User talk:Pinsplash|talk]])'' 17:32, 31 August 2018 (UTC)

=== Encouraging and enforcing better formatting ===
I think the use of "I" should be strongly discouraged and edited out of non-talk articles. It's bad form, strips neutrality and adds potential bias; documentation should be mostly formal. --[[User:Stract|Stract]] ([[User talk:Stract|talk]]) 21:11, 6 July 2018 (UTC)

I've already been editing that out whenever I see it, it definitely needs to be eradicated.--[[User:Ficool2|Ficool2]] ([[User talk:Ficool2|talk]]) 21:14, 6 July 2018 (UTC)

[[Special:WhatLinksHere/Template:Pov|This would be a good place to start.]] Stuff like "I don't know how to fix this currently" should be replaced with something like "<nowiki>{{todo|How to fix?}}</nowiki>" [[User:Pinsplash|Pinsplash]] ([[User talk:Pinsplash|talk]]) 21:26, 6 July 2018 (UTC)
__TOC__

=Old stuff=
==usefulness?==
Wouldn't these templated entity pages become somewhat redundant with quasi-tutorial pages like [[Assaults]]? 
Or should these entity pages be kept as placeholders until more expansive pages can be written? --[[User:Demented|Demented]] 15:25, 4 Jul 2005 (PDT)

== More description? ==
I've been using this site a lot when seeking information about entites, but these templates are just the same as in hammer.
And the most of them in hammer generally suck; the most of them is just like: ''This is an Antlion.'' Followed by a lot of keyvalues.
So would anyone mind if I improve the description of the entites, from ''This is an Antlion'' to eg. ''This is an Antlion. They are enemies in hl2, and generally hides under the sand, until the player touches it. They are being spawn with a npc_antlion_template_maker.'' Or something like that?
--[[User:Sortie|Sortie]] 09:16, 4 Feb 2007 (PST)

== Feedback ==

I think this template could use some improvements.

* First off, it's missing a Flags section, which I think most entities have.
* The entity name under the description isn't needed. The name is right at the top of the page already, and duplicating it just takes up more space.
* I think it could use some horizontal rules between the Entity Data sections. I looked at [[Env_fire]] -- it looks easier to read to me. Is the Entity Data section headline needed at all? It makes the article layout and the table of contents noisier, but that's debatable I guess. The format of the keys in the template seems better though, where the whole thing isn't bold, only the name of the key.
--[[User:IanL|IanL]] 11:58, 9 Jul 2005 (PDT)

: Hooray! Constructive criticism! :-) 

: Ideally, I'd write a script to convert stuff from the FGD into the correct format, but that of course depends on me assigning some of my copious free time to the task. The current arrangement of headers and things makes a bit more semantic sense to me, but visually it's not so great. I think returning to <nowiki>==These Headings==</nowiki> might improve that, as per your suggestion...

: Flags? The text isn't present in the copied-and-pasted 'Help' text in Hammer, but can almost certainly be extracted by my hypothetical script.

: Anyhow, when some final design is decided on (feel free to edit!), I can do some batch conversion with my fabled, non-existent script and make everyone happy. While the FGD-based information is hardly sufficient for a complete Wiki, I do feel it's useful data that can be used as a basis for more extensive work.. --[[User:Cargo Cult|Cargo Cult]] 12:08, 9 Jul 2005 (PDT)

:: OK, I'll make a couple edits. Yeah, the flags aren't in the help output. I just looked in an FGD, and the info is in there. I wonder why they didn't do that. Must be a formatting thing or something. It seems like there's a lot less flags in Source than there was in Half-Life 1, anyway.

:: I'm really unsure on the header thing myself. The one thing the extra level of heading does is give room to add new larger section to the article later, like a tutorial or usage section.  --[[User:IanL|IanL]] 12:23, 9 Jul 2005 (PDT)

I'm probably going to get an unbelievable amount of stick for suggesting this (as most entities have already been documented with this template) but shouldn't the ''Entity description'' be under the headline, above the TOC? In contrast to how it is positioned now, under the TOC, having its own header. Most of the descriptions seem to.. well.. describe what the entity is and how it behaves, this IMO should be right in the opening "intro" paragraph of the entity article. [[User:Jupix|Jupix]] 06:06, 4 Feb 2007 (PST)



== User inputs and outputs ==

The FireUserX inputs & corresponding OnUserX outputs are valid on every single entity in the game, and actually have nothing to do with the particular entity itself. Instead of bloating every entity description with them, it might be good to link to a single article that explains how they work and what they're for. -- [[User:Robin Walker|Robin Walker]] 13:53, 9 Jul 2005 (PDT)

::Yeah, that seems like a good idea. The help built-in to Hammer should do that, too. ;)
::The only question is where to put the link. Should we just add it to the base Entity category page, or add the link to every entity description? I lean towards the former. The problem is, I don't think these outputs are used very often, but they're very visible. --[[User:IanL|IanL]] 14:02, 9 Jul 2005 (PDT)

: Heh, and I'd been religiously copy-and-pasting the formatted versions from my entity article template... Silly question, though - what do the OnUser''n'' things actually ''do''? I've yet to figure it out! :-)

:: The FireUserN input simply causes the corresponding OnUserN output to fire. They're useful for forwarding messages through an entity where the desired target is known to the forwarding entity, but not to the firing entity. For example, say you have 3 trains moving along the same set of path_tracks. Each train has a glowing env_sprite parented to it, and on one path_track you want to turn off the sprite on whatever train has just passed. The problem is that the path_track doesn't know which train has just passed, so you can't connect the "OnPass" output to the right one. So, you solve this by connecting the path_track's "OnPass" output to the !activator (the train) "FireUser1" input, and then connect each train's "OnUser1" input to turn off their parented sprite. 
::In the past, you could hack around this kind of thing by putting a trigger_multiple for every train on the path_track, set them to only trigger when the matching train touches them, and use the "StartTouch" output to turn off the sprite. Unfortunately, that method doesn't scale to large numbers of trains (as seen in the citadel). -- [[User:Robin Walker|Robin Walker]] 18:17, 9 Jul 2005 (PDT)

:::I shamelessly ripped off this explanation as the basis for [[User Inputs and Outputs]]. It ''is'' a subject that can be a little tough to wrap your head around at first, but when you need it, it's invaluable. --[[User:JeffLane|JeffLane]] 21:16, 9 Jul 2005 (PDT)

:::Oooh, excellent. Thanks for that - and many thanks for all the other bits and pieces of Half-Life 2 and Source that you're documenting! --[[User:Cargo Cult|Cargo Cult]] 11:46, 11 Jul 2005 (PDT)

: With regard to oft-duplicated content, there's also a lot of stuff for the NPCs which gets spread around, like AI node information for [[npc_sniper|snipers]]. Any thoughts on that?  --[[User:Cargo Cult|Cargo Cult]] 14:14, 9 Jul 2005 (PDT)

::It looks like someone is making templates for some of the common keyvalues right now. --[[User:JeffLane|JeffLane]] 21:16, 9 Jul 2005 (PDT)

== SmartEdit values ==

I can't find my way around these keyvalues because I (probably along with most people) use SmartEdit. I'd like to list the SmartEdit keyvalues for the entities instead, but need to run this by you to make some kind of new standard. Preferably I'd like to list the values as "SmartEdit keyvalue (FGD keyvalue)". For <code>logic_auto</code>, that would probably be "Global State to Read (globalstate)".
What do you think?
--[[User:Andreasen|Andreasen]] 17:15, 29 Jan 2006 (PST)

this is most likely not okay because we already have hundreds of entities documented...this would be ok if anyone wanted to run through '''all''' of them and fix them up&mdash;'''[[User:Ts2do|ts2do]]''' 18:03, 29 Jan 2006 (PST)
:I know it would be really hard work to convert them all, but it would probably improve things a ''great'' deal for beginners. If we could make some kind of small note to the new or old standard pages, linking them to this Entity_Article_Template article to inform them of a new standard, the wiki community might just be able to convert the pages gradually without confusion. I mean the old values would still be there, as a part of the new format too, but just in another position. --[[User:Andreasen|Andreasen]] 09:55, 31 Jan 2006 (PST)
:: I agree with this. The entity help built into Hammer lists boths the SmartEdit names and the "real" keyvalue entries for this exact reason. I don't see any reason why this formatting couldn't be added incrementally, and I think it's worthwhile, but it is up to the community to decide whether they wish to take task on. There is a fair amount of the basic data shared in templates, which would shorten the time needed. --[[User:JeffLane|JeffLane]] 12:01, 31 Jan 2006 (PST)

== Availabililty templates ==
{{note|These template have been deprecated. They are kept here for historical purposes, but please use {{tl2|this is a}} instead}}
There a couple of entity templates by Maven/Ts2do which seem useful and noteworthy for example see [[game_player_equip]] --[[User:Beeswax|Beeswax]]
* [[Template:In_game]] flags '''Brush-based entities'''. Use <code><nowiki>{{in game|brush}}</nowiki></code>.
* [[Template:In_game]] flags '''Point-based entities'''. Use <code><nowiki>{{in game|point}}</nowiki></code>.
* [[Template:Game-base]] flags '''base.fgd entities'''. Use <code><nowiki>{{game-base}}</nowiki></code>.
* [[Template:Game]] flags '''halflife2.fgd entities'''. Use <code><nowiki>{{game|HL2}}</nowiki></code>.

== Entity Properties Table - alternative layout ==

Here's an example of an alternative way of presenting the entity properties. 

* This is quite a crude version using current templates, but if you look at the code you will see how the [[BaseClass_fgd]] property templates can be simplified : if each BaseClass is given a single table row, each BaseClass template can include all keyvalues, flags, inputs and outputs - no need for the awkward splitting into 4 separate kv_, fl_, i_, and o_ templates. For the reader this also means that where a keyvalue has a corresponding input (eg parentname & Setparent) the relationship is easier to understand. BaseClass properties do tend to relate to the same areas of functionality - that's why they're grouped into BaseClasses I guess ;-)

* (As a seperate project) I've been linking the "keywords" to articles which explain their usefulness and quirks more discursively. More needs to be done, but this should allow us to lighten the information load on these properties tables, keeping them to a minimum definition and description. This should save space and help the table fit together better. Discursive usage notes on the entity-specific properties should probably go in (a subsection of?) the Entity Description section.

* I've used some npc_turret_floor data for the example. Notice that the top row should be the entity-specific properties, as these are most relevant to entity-specific pages. The most common entity properties (eg targetname) should sink to the bottom of the list, as these will be more familiar - less urgent - to the reader.

{{clr}}
{|
|-align="left"
![[Keyvalue]]s
![[:Category:Flags|Flags]]
![[Inputs and Outputs|Inputs]]
![[Inputs and Outputs|Outputs]]
|-valign="top"

|<!--Keyvalues-->

*; SkinNumber <integer> : Which skin to use for this turret. Set to 0 to select randomly.

|<!--Flags-->

* 32 : Autostart
* 64 : Start Inactive
* 128 : Fast Retire
* {{EP1 add|256 : Out of Ammo}}
* {{EP1 add|512 : Citizen modified (Friendly)}}

|<!--Inputs-->

*; Toggle : Toggle - If open, close. If closed, open.

*; Enable : Enable the turret.

*; Disable : Disable the turret.

*; DepleteAmmo : Depletes all the ammo from a turret, causing it to dry-fire.

*; RestoreAmmo : Restores ammo to a turret, allowing it to fire live rounds again.

*; SelfDestruct : Causes the turret to warn and then explode.

|<!--Outputs-->

*; OnDeploy : Turret is becoming active and dangerous.

*; OnRetire : Turret is becoming inactive and harmless.

*; OnTipped : Turret has been tipped over and is inactive.

*; OnPhysGunPickup : Picked up with physgun.

*; OnPhysGunDrop : Released by physgun.

|-valign="top"
|<!--Keyvalues-->
*{{KV Angles}}
|<!--Flags-->
|<!--Inputs--> 
|<!--Outputs--> 

|-valign="top"
|<!--Keyvalues-->
*{{KV Parentname}} 
|<!--Flags-->
|<!--Inputs--> 
*{{I Parentname}} 
|<!--Outputs--> 

|-valign="top"
|<!--Keyvalues-->
*{{KV Targetname}} 
|<!--Flags-->
|<!--Inputs--> 
*{{I Targetname}} 
|<!--Outputs--> 
*{{O Targetname}}

|}{{clr}}

--[[User:Beeswax|Beeswax]] 04:31, 9 Mar 2008 (PDT)

== See also & information hierarchy ==

"See also" links should be moved into the "Description & Usage" bit at the top of the page. My reasoning is this: 

* Because of all the (highly repetitive and poorly documented) keyvalue material on every entity page, I often find my brain goes numb if I try reading beyond the Description ;-)

* Very often the "See also" links are actually "Stuff You Should Read Before You Read This Page!". Links to sibling entities, comparable entities, tutorials, relevant articles, etc. should therefore be part of an "Introduction and Orientation" to the entity - not relegated to the foot of the page into a kind of "further reading" section. 

* For Example: An Entity Doc like [[info_node]] contains very specific data, and is not really the best place to try and explain, say, how nodegraphs work - better to read the (excellent) [[nodegraph]] article first, then look at [[info_node]] if necessary. In a sense, [[info_node]]'s property data is a footnote to the [[nodegraph]] article - not the other way around. 

* Using this hierarchy logic, I can't think of any cases where a list of Entity Properties Keyvalues would require a "Further Reading" section, unless possibly to delve into the Entity's Source Code ?

Does that make sense ? --[[User:Beeswax|Beeswax]] 06:07, 16 Apr 2008 (PDT)