Talk:SDK Docs

From Valve Developer Community
Revision as of 09:59, 30 April 2009 by Fitzroy doll (talk | contribs) (1. Over-categorization: Help with dividing HL2, EP1 and EP2 entities)

Jump to: navigation, search


Please do not edit the archives

Restructuring the category pages

I would like to restructure the categories section from their current implementation for what I believe would be easier navigation. My two suggested changes are stated below. --brandished 05:24, 27 March 2009 (UTC)

1. Over-categorization

I feel many of the categories, such as entities and level design are covering a topic ranges a bit too broad to be useful to most users. I'd like to restructure according to these guidelines from Wikipedia:

An article will often be in several categories. Restraint should be used, however — categories become less effective the more there are on a given article.
An article should usually not be in both a category and its subcategory, e.g. Microsoft Office is in Category:Microsoft software, so should not also be in Category:Software—except when the article defines a category as well as being in a higher category, e.g. Ohio is in both Category:U.S. states and Category:Ohio

For an example, a category I feel would benefit from this is Category: entities. I would like to remove articles related to specific entities from the parent category entities and place them only in subcategories instead. My arguments for this are:

  1. There is no clear delimiters as to which game engine, game, or mod certain entities are available for. Many of the articles listed in the main category will be of little to no use to users who don't own those specific games
  2. The current tags groups many mostly unrelated articles together.
--brandished 05:24, 27 March 2009 (UTC)

According to wikipedia -
If category B is a non-distinguished subcategory of category A, then pages belonging to category B (directly or through further subcategories) are not placed directly into category A.
If category B is a distinguished subcategory of category A, then pages belonging to category B are placed directly into category A if otherwise appropriate.
If we were to create categories like Entities:Half-Life 2, Entities: Portal, etc. for each game, then the entities that are only in those games would NOT go into the general entities and into the game entities category. However, if an entity is shared between all games it should go into Entities. If an entity is shared between a couple games then it would go into each of the game entity categories and NOT into Entities.
For instance, info_player_start would go into only Category:Entities because every game has that. func_liquidportal would only be in Category:Portal Entities. If we have a Category:NPC Entities, anything in that category would also go into Category:Entities. However if we have a Category:Half-Life 2 NPC Entities, anything in that category would also be in Category:Half-Life 2 Entities because Category:Half-Life 2 NPC Entities is a distinguished subcategory of Category:Half-Life 2 Entities and none of the pages would be in Category:Entities. I hope this makes some sense because it's kind of a hard thing to explain. If you want, I can try to properly categorize all entities on a page this weekend for review.
--Remmiz 23:57, 27 March 2009 (UTC)
I understand what you are saying, an entity that could be placed in all subcategories going in the parent category. It gets tricky though, some entities that you would think would work in all Source games don't (eg: func_rotate). I'm still not quite sure how to organise all the Half-Life 2 specific entities between H-L2, EP1, EP2, H-L2 Deathmatch and Portal. --brandished 13:02, 29 March 2009 (UTC)
I would say if it belongs to every game, it goes into Category:Entities. If it belongs to more than one but not all, you would put it into each game's entity category. For the Episodes, I'd say to make a Half-Life 2 Entities category. Then have Episode 1/2/3 entities be sub-categories of Half-Life 2. So Category:Half-Life 2 Entities would have all entities that are shared between Half-Life 2, Episode 1, 2, and 3. Category:Half-Life 2 Episode 1 Entities would only have entities that are specific to Episode 1, etc. --Remmiz 18:47, 29 March 2009 (UTC)
Hmm... I was thinking of something similar, the only possible problem I can think of is the one I described below, where if there were too many subcategories making it a hassle to scroll down to the actual entities. The other option I was thinking of was having a "Category: Base Entities", but that might be difficult to integrate into other categories. It might be a good idea to draw up some mock-ups first and get an idea of what the final concept will actually look like. --brandished 22:55, 29 March 2009 (UTC)
Thanks for your attention to all this. According to the general guidelines of wikis and the discussion above, the only way that would seem to make any sense would be the following:
  • Parent Category: Entities
  • Subcategory: HL2 Entities
  • Sub-subcategory: HL2 NPCs
  • Sub-subcategory: HL2 Vehicles
  • Subcategory: Episode 1 Entities
  • Sub-subcategory: Episode1 NPCs
  • Sub-subcategory: Episode1 Vehicles
  • Subcategory: Episode 2 Entities
  • Sub-subcategory: Episode2 NPCs
  • Sub-subcategory: Episode2 Vehicles
  • Subcategory: Portal Entities
  • Sub-subcategory: Portal NPCs
  • Subcategory: and so on....
Everything that is in a child category goes in the parent, full stop. The recurring example of func_liquidportal will go into Entities and Portal Entities. And yes, a logic_auto will go into all of the above main sub-categories as well as the parent category Entities. This is normal and not a problem.
As pointed out above, the difficult part is going to be determining the games in which each entity is available. Your task is made relatively straightforward by the fgd system: in sourcesdk\bin\ep1\bin you will find a base.fgd. This contains entities available for all games. The entities specific to each game are then found in each named fgd such as halflife2.fgd. By using a text editor to sort the contents of a copy of each fgd you can quickly get a list of classes and these correspond to the entries in this wiki. It may not produce perfect results, but it will be a start, which we can all then modify.--Fitzroy doll 11:13, 7 April 2009 (UTC)
Hmm, do you know how Hammer determines which entities from the base fgd to filter out for specific games such as CS:S and TF2? I thought it was done through fgd files, but I'm not seeing (or am overlooking) the values. --brandished 02:55, 16 April 2009 (UTC)
I don't think it does filter them out. As far as I am aware, all entities in the base.fgd are available to hammer in all games. This can lead to things appearing which do not work, for example, if you start up Hammer with the Episode 1 engine and Half Life 2 game selected, you can put a func_fish_pool in your map, but in-game, running under HL2, the entity will not work. For now, given that the FGD is the only external standard which exists, you may want to base inclusions in each category solely on the fgds, and then over time users of the VDC can fine tune it if required. --Fitzroy doll 10:13, 16 April 2009 (UTC)
You might find these lists useful for this task.--Fitzroy doll 10:20, 17 April 2009 (UTC)
Ah, you beat me to it, how long ago were these pulled? I had a script for pulling entities, but it had some problems and I had to revise it. I just finished working on yesterday, but was too tired to run it. Also, is it worthwhile to include the "BaseClass" and "FilterClass" entities? If I'm understanding them correctly, I don't think they can be accessed directly, only through other entities. --brandished 20:43, 17 April 2009 (UTC)
These were generated this morning, so they should be current. Any entity with a class "BaseClass" or "BaseClass base" does not need its own entry - I included them only for completeness. Having looked at these lists, I would now suggest that there should be 7 main categories (corresponding to Base and the 6 main games). EP1 and EP2 would now probably make more sense as sub-categories of HL2 rather than as categories of their own.--Fitzroy doll 20:57, 17 April 2009 (UTC)
I agree with EP1 and 2, I didn't realize until I started working on these entity lists that HL2, Ep1, and Ep2 all shared the same entity list. I'm guessing Valve was planning on moving their whole Source game library over to the Orange Box engine, but decided against it, probably to keep from moving the system requirements outside the capabilities of game owners on older hardware. Anyways, thanks for putting this list together, it makes a great resource and definitely saves me some time. For now, I'm just planning on making sure the game-specific entity lists on all the game-specific level design pages are up to date. Maybe also have all entities available for the each game on one page, but keep the new, game-specific entities separate from the "base" entities and then comment out the base entities that don't work for those games. Once that gets done, work on categorizing from there. I'd like to also at some point update a lot of the individual entity pages to include several example uses of each entity, similar to how the sky list pages are set up now with the different example settings for each map, but that's another matter. --brandished 10:54, 21 April 2009 (UTC)
You might also find this list helpful: Unknown Entities in HL2, EP1 and EP2. It was generated by running the ent_info command in game in HL2, EP1 and EP2 against every entity in the base and HL2 fgds. Many of these entities cannot be generated in game because they are entities that are dealt with only by vbsp, such as prop_static. Some don't work because they are not supported by that game's code. In some cases both exclusions apply. It should be fairly easy to tell which is which, but the only way to be sure (as far as I am aware) would be to create a map with all listed entities in each game and see what doesn't get compiled.--Fitzroy doll 09:59, 30 April 2009 (UTC)

2. Splitting apart category pages from entry pages

A lot of the large category pages, such as Category: Level Design, I believe have become too overloaded with content to be easily used as WiKi categories. Many of the categories with these problems are linked directly to the "SDK Docs" page. The actual categorized pages are being over looked and unused by many due to having to scroll to the very bottom of the most of the linked pages to see the actual categorized pages with their current set-up. This problem is compounded if an article in the category is not located within the first 200 results, after clicking next users are forced to scroll through all the contents again to get to the categorized pages. To be clear, I'm not saying get rid of the Category pages, but just moving the table-of-contents parts into regular articles. On other Wikis, category pages are used primarily for cross referencing, not as entry pages.

For example, the lower half of Category: Level Design, starting from "Subcategories" and below, would remain along with the categorized pages, but table of contents portion above that would be moved outside of the category into an article page.

eg, instead of the main page being located at "Level Design", the new location for the table-of-contents parts would be "Level Design", with a link at the top of the category page something like The main article for this category is Level Design

Here's some parent categories on the Wikimedia Foundation's projects for further demonstration:

--brandished 05:24, 27 March 2009 (UTC)
I imagine that the reason the main article for each section is a category and not an article is that each article added to the category automatically shows up on the main article page, but given the number of articles this is not ideal. The solution suggested above seems very sensible to me.--Fitzroy doll 11:59, 7 April 2009 (UTC)