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.

1. 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.
2. Add non-SmartEdit versions of keyvalues next to their SmartEdit names. This may or may not include changes to Template:KV.
3. 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).
4. 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 RunScriptFile 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. --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 this Discord server Pinsplash (talk) 10:54, 4 July 2018 (UTC)

Bumping this again since people are coming back onto the wiki now. 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. --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! 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. 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. --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.--Ficool2 (talk) 21:14, 6 July 2018 (UTC)

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 "{{todo|How to fix?}}" Pinsplash (talk) 21:26, 6 July 2018 (UTC)

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? --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? --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.

--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 ==These Headings== 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.. --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. --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. 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. -- 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. --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 OnUsern 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). -- 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. --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! --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 snipers. Any thoughts on that? --Cargo Cult 14:14, 9 Jul 2005 (PDT)

It looks like someone is making templates for some of the common keyvalues right now. --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 logic_auto, that would probably be "Global State to Read (globalstate)". What do you think? --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—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. --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. --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 {{this is a}} instead

There a couple of entity templates by Maven/Ts2do which seem useful and noteworthy for example see game_player_equip --Beeswax

• Template:In_game flags Brush-based entities. Use {{in game|brush}}.
• Template:In_game flags Point-based entities. Use {{in game|point}}.
• Template:Game-base flags base.fgd entities. Use {{game-base}}.
• Template:Game flags halflife2.fgd entities. Use {{game|HL2}}.

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.

Keyvalues	Flags	Inputs	Outputs
SkinNumber <integer>  Which skin to use for this turret. Set to 0 to select randomly.	32 : Autostart 64 : Start Inactive 128 : Fast Retire 256 : Out of Ammo (in all games since ) 512 : Citizen modified (Friendly) (in all games since )	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.	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.
Pitch Yaw Roll (Y Z X) (angles) <angle> This entity's orientation in the world. Pitch is rotation around the Y axis, yaw is the rotation around the Z axis, roll is the rotation around the X axis.
Parentname: Parent (parentname) <targetname> Specifies a movement parent. An entity will maintain its initial offset from its parent. An attachment point can be added to the end of the name, separated by a comma.		Parentname: SetParent <string> Move with this entity. See Entity Hierarchy (parenting). SetParentAttachment <string> Change this entity to attach to a specific attachment point on its parent. The entity will teleport so that the position of its root bone matches that of the attachment. Entities must be parented before being sent this input. SetParentAttachmentMaintainOffset <string> As above, but without teleporting. The entity retains its position relative to the attachment at the time of the input being received. ClearParent Removes this entity from the the movement hierarchy, leaving it free to move independently.
Name (targetname) <string> The name that other entities refer to this entity by, via Inputs/Outputs or other keyvalues (e.g. parentname or target). Also displayed in Hammer's 2D views and Entity Report. See also:  Generic Keyvalues, Inputs and Outputs available to all entities

--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 ? --Beeswax 06:07, 16 Apr 2008 (PDT)