Jump to content
The Dark Mod Forums
Sign in to follow this  
SneaksieDave

Some entity properties not listed; which and why

Recommended Posts

That script looks practical, good work. :)

 

I had the idea to make an entity_base def a few days ago. Spawnargs that can be used on all kinds of entities (like health, the new absence spawn args, frobablility...) could be documented there. Your script would come in handy for finding duplicate definitions too. :)

 

The base entity sounds like a good idea :) Also, I was thinking about the difference of "func_static" and "atdm:static_entity". We probably should encourage the usage of "atdm:foo" entities all over using D3 entity classes like "func_static". One example is "func_liquid" which really shouldn't be used (use "atdm:liquid" instead).

 

People still too often start with a func_static and then wonder wether they can set "frobable" on it. That's the wrong question, they should use "atdm:frobable_base" instead :)

 

So we can either try to make them use the right base-class, or we need to move the documentation of relevant spawnargs (like frobable) to func_static instead. (Not sure which is more praktical and would actually work - changing peoples habit is hard :)


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Okay, here is the update for today :)

 

I completely rewrote the documentation-generating script devel/inspect.pl - it now only generates one file:

 

* devel/doc/js/entities.js

 

This is a Javascript representation of all the information gathered from the def files. It is about 550Kbytes big atm.

 

Together with these three (four) files:

 

* devel/doc/js/tdm.js (the main JS application showing the doc in your browser)

* devel/doc/js/prototype-1.6.0.2-packer.js (The protoype Javascript library in compressed form)

* devel/doc/css/tdm.css (stylesheet defining the look and color)

* devel/doc/index.html (tiny index.html stub responsible to load the JS and kickstart it)

 

this represents the online/live documentation of TDM about entities, files and spawnargs.

 

Since there are now only 5 files and they are small (compared to over 6Mbyte for the first version :) I checked them into SVN. So if you want to read it you need to:

 

* update SVN

* browse to devel/doc/index.html with your browser (so far only tested Firefox, Opera and Konqueror, but should work in Safari, too. Can somebody please test with IE?)

 

You can also see an online version in case you don't have SVN:

 

* http://bloodgate.com/mirrors/tdm/pub/doc/index.html (I try to update it frequently)

 

If you modify the def files and want to regenerate the documentation, run:

 

* perl devel/inspect.pl

 

then reload the page in your browser.

 

Here are a few screenshots:

 

post-144-1228592271_thumb.png

 

post-144-1228592289_thumb.png

 

Not everything works, it is still WIP. The amount of undocumented spawnargs is not quite correct, because "used_by_n" is documented, while f.i. the spawnarg is named either "used_by" or "used_by_1", and the JS doesn't quite understand these subtle cases :)

 

Next post contains a few observations :) Have fun :D


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

We have about 1500 unique spawnargs (ouch!) - from these are about 1/3 (about 500 documented), which leaves us with about 1000 to document.

 

However, we have whole hosts of spawnargs which we can document in groups (f.i. "snd_something" so it is not as much work as it looks :)

 

Also, while looking at these lists I found the first bug in our def files:

 

te@te-laptop:~/.doom3/darkmod$ ack ammoReq def/ -B16
def/tdm_prop_items.def
123-
124-entityDef torch_lantern_on {
125-	"inherit"				"atdm:prop_base"
126-	"editor_usage"  "A lit lantern to be carried in the left hand."
127-"model" "models/darkmod/lights/non-extinguishable/hooded_lantern.lwo"
128-	"skin"		   "skins/models/md5/props/lantern/lantern_on"
129-
130-	"joint"			  "LeftHand"
131-	"origin"				 "4 0 0"
132-	"angles"				 "0 0 0"
133-	"remove"				 "1"
134-
135-	"weapon_scriptobject"		   "weapon_lantern"
136-	"def_melee"									 "damage_lantern"
137-	"melee_distance"						"48"
138-	"ammoType"									  ""
139:	"ammoRequired"						  "0"

 

However, the correct names would be "ammo_type" and "ammo_required" :)

 

Two spawnargs less to document :P


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

One more bug found:

 

used_by_n 	var 	Contains an entity name (of keys) that can unlock/lock this door. Multiple used_by keys are possible by numbering them (like 'used_by_3'). 	atdm:mover_door

 

However, the code does this:

 

te@te-laptop:~/src/trunk$ ack used_by
game/entity.h
282:	 * "used_by" "*holy_fountain;*holy_bottle;holy_cro
ss"

game/entity.cpp
7320:   for (const idKeyValue* kv = spawnArgs.MatchPrefix("used_by"); kv != NULL; kv = spawnArgs.MatchPrefix("used_by", kv))
7580:   // Check if the entity's name is in the used_by list

 

which is symmetric to:

 

te@te-laptop:~/src/trunk$ ack can_unlock
game/ai/ai_events.cpp
550:	for (const idKeyValue* kv = spawnArgs.MatchPrefix("can_unlock"); kv != NULL; kv = spawnArgs.MatchPrefix("can_unlock", kv))

 

but "can_unlock" says you need to put "can_unlock2" (not "can_unlock_2"!).

 

So is the description of "used_by" wrong, or are both variants actually allowed? (That would complicate matters even more :o


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Good work. :)

 

That's a lot of undocumented spawnargs! Thankfully there are lots of classes of spawnargs e.g. attach_pos_angles_JOINTNAME where JOINTNAME is... any joint name. (Is there a good way to document these group spawnargs though?)

 

As the name suggests, idDict::MatchPrefix will match any spawnargs whose names start with the given prefix. So can_unlock2, can_unlock_2, can_unlockpotatoes, and can_unlock_tomatoes will all work in that case.

 

MatchPrefix is commonly used for many of the spawnargs that can be specified multiple times by using different suffixes (but not for all of them).


My games | Public Service Announcement: TDM is not set in the Thief universe. The city in which it takes place is not the City from Thief. The player character is not called Garrett. Any person who contradicts these facts will be subjected to disapproving stares.

Share this post


Link to post
Share on other sites
Good work. :)

 

That's a lot of undocumented spawnargs! Thankfully there are lots of classes of spawnargs e.g. attach_pos_angles_JOINTNAME where JOINTNAME is... any joint name. (Is there a good way to document these group spawnargs though?)

 

Good question. I teached the JS a small list of common prefixes, but it would be better if there was a way to encode this somehow directly in the def file, so DR also knows about it. (Actually, there are quite a lot of "foo_blah_N" spawnarg descriptions, so maybe we just need to unify them all and teach DR about it?)

 

For now, the idea is that you document "def_attach_joint", and the editor or JS then knows that this applies to all "def_attach_joinFOOBAZ" spawnargs.

 

One more thing that opens up is, however, how to know which suffix is valid in case the suffix must be something like a joint. A typo would be an error here.

 

As the name suggests, idDict::MatchPrefix will match any spawnargs whose names start with the given prefix. So can_unlock2, can_unlock_2, can_unlockpotatoes, and can_unlock_tomatoes will all work in that case.

 

MatchPrefix is commonly used for many of the spawnargs that can be specified multiple times by using different suffixes (but not for all of them).

 

Ah yes I wasn't thinking clearly. So any suffix is fine, as long as they are consistent. Hm, that means we need to list somewhere everything that is every used with MatchPrefix to catch them all.


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites
For now, the idea is that you document "def_attach_joint", and the editor or JS then knows that this applies to all "def_attach_joinFOOBAZ" spawnargs.

I guess that's sufficient, actually; just document attach_pos_angles_JOINTNAME, and mention in the description for it that you "must replace JOINTNAME with the name of a valid joint". Similarly for stuff like can_unlock which accepts arbitrary suffixes.

 

So any suffix is fine, as long as they are consistent.

Actually the suffixes don't even need to be consistent. ;) The suffix is completely ignored (except in very specific cases where it specifies a joint name or whatever). It can be anything.

 

Hm, that means we need to list somewhere everything that is every used with MatchPrefix to catch them all.

Prefixmon: Gotta catch 'em all!

 

Seriously though. :P We don't necessarily need to do that. The easiest route is to just document the spawnarg prefix (like "can_unlock"), and then mention in the description that you can also do can_unlock_blah or whatever.

 

The point of having "all spawnargs documented" is not to pre-fill every single possible variation of the spawnargs. It's just to let mappers know what is available. They're smart enough to read the documentation and modify spawnarg keys as necessary (to fill in joint names, or number successive spawnarg keys so they can enter more than one, or whatever), so we don't need any code support to do that for them.


My games | Public Service Announcement: TDM is not set in the Thief universe. The city in which it takes place is not the City from Thief. The player character is not called Garrett. Any person who contradicts these facts will be subjected to disapproving stares.

Share this post


Link to post
Share on other sites
Seriously though. :P We don't necessarily need to do that. The easiest route is to just document the spawnarg prefix (like "can_unlock"), and then mention in the description that you can also do can_unlock_blah or whatever.

 

I know what you are saying, but I was talking about a different issue: How to teach the computer that the spawnarg "Picachu_FOO" is actually documented, because a documentation for "Picachu" exists.

 

That case is important for the "List of Undocumented Spawnargs" because as soon as someone adds

 

"editor_var Picachu" "Wigglytuff (プクリン, Pukurin?) is a relatively large pink balloon-like Pokémon with a white underbelly, large blue baby-like eyes, a pair of large rabbit ears, and a twisty tuft of pink hair on its forehead."

 

we want "Picachu_FOO" to vanish from that list :)

 

The "just mention in the description" is a mess, because it is A: not machine readable and B: even difficult for humans, because every spawnarg describes that differently.

 

What I'd like to have is a machine-readable list, so at least the documentation in JS can show you "Yes, this is a suffix, attach anything you like to add more of these." Once we have that, it could even be read by DarkRadiant in the future :)


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

I have started to document a few spawnargs that were added by me (shame on me I should have done this right away :blush: ) and TDM in general. Also started to change the editor_var to the more fitting editor_bool etc to help the user in selecting the value.

 

Also, the documentation now shows the entity list (not yet sorted into a classtree yet).

 

However, while doing so, it seems every time you look, you find strange things :(

 

Why, for instance, do we have a nonsolid boolean spawnarg, as well as a solid one? Not only would one suffice, but now they can actually contradict each other (and I am not sure what the code does in this case, anyway).

 

Removing one is tracked now here:

 

http://bugs.angua.at/view.php?id=1555


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

I can't say how many times over the years I've run into nonsolid and solid. It seems every single time, I forget which is the 'correct' one, which one to use.

 

The documentation effort is rocking, btw. Wow.

Share this post


Link to post
Share on other sites

Laugh of the day:

 

On func_rotating:

 

speed: determines how fast it moves.

 

degrees per second?

 

This reminds me of the voluminous pdf crap that came with my overpriced monitor. When I looked up 'blacks' it said something like 'adjusts the blacks'. Thanks NEC.

Share this post


Link to post
Share on other sites
Laugh of the day:

 

On func_rotating:

 

speed: determines how fast it moves.

 

degrees per second?

 

This reminds me of the voluminous pdf crap that came with my overpriced monitor. When I looked up 'blacks' it said something like 'adjusts the blacks'. Thanks NEC.

 

LOL :) If you find out something about a spawnarg, then please just adjust the documentation :)


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

I just updated the JS code that displays the doc:

 

* the overview page now has a list with some important TDM links (wiki, forum, main, tracker)

* the headline was moved from the top to the inside of the content div of the overview page. That means it is no longer wasting space on all the other tabs. Also made the footer a bit smaller, and attached a bit of JS that resizes the inner content pane to be exactly as big as it needs (it is unfortunately not possible to specify the size in CSS like "100% - 5em", so I had to set the size at some arbitrary percentage. The 78% were to small for my PC monitor, but 79% is too big for my laptop. Now the content always consumes the left-over space :)

 

Before and after shots:

 

Overview:

 

post-144-1228929108_thumb.png

 

post-144-1228929120_thumb.png

 

Entity list:

 

post-144-1228929147_thumb.png

 

post-144-1228929303_thumb.png

 

 

I have also documented 3 more spawnargs..oh boy this is going slow :(


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Some more work on the JS GUI for the doc, this time also updated the online version at http://bloodgate.com/mirrors/tdm/pub/doc/ :)

 

* the entity list now has links to each entity

* such a link leads to a new tab, which displays this entity with the spawnargs

* this view also contains an inheritance chain showing the inheritance

 

So now the new interactive version can do all what the old can, and more :)

 

The new view has still some WIP issues:

 

* the chain can overflow and this is not yet handled properly, also the list "entities that use the current entity" is still missing.

* no inherited spawnargs are shown yet

 

Anyway, comparisation between old and new:

 

http://forums.thedarkmod.com/index.php?act=a...ost&id=2900

 

post-144-1229007081_thumb.png


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Good work so far.

 

I'm wondering how far you want to go with this? Not that I wouldn't appreciate the nice JS frontend, but where's the journey going?

Share this post


Link to post
Share on other sites
Good work so far.

 

I'm wondering how far you want to go with this? Not that I wouldn't appreciate the nice JS frontend, but where's the journey going?

 

Important:

 

* The "inherited" spawnargs need to be shown for each entity Done 2009-01-03

* The deprecated entities need to be in a sep. list

* The search should work Done 2009-01-03

* Want to resolve the "back/forward" button issue (this is a general JS issue and I have an idea, if it works, we get the solution for free since I need it for all my JS apps :) Done 2008-12-16

 

Each of these is maybe 1 hour work, except the last, which is maybe 10 minutes.

 

(I guess the frontend looks much more work than it actually was :)

 

Nice to have:

 

* want the tables to be resortable by clicking on the header

* the spawnarg type should be represented by a little icon just like in DR (Can I borrow DRs icons?)

 

Not now:

 

* Somebody also asked about skins/materials etc. These *could* be included, but for the moment I don't want to go this route - it is a lot of work.

 

 

The main issue, namely that we need somebody to document entities and their spawnargs, is still open. But since this is work that can be done by somebody even without programming experience, I leave that for others :)

 

Edit: Marked items as done. 2008-01-03


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Not sure if this is the right thread but I notice that properties already set are not in the add properties list. So if you want to find out what they do you have to delete them then add them again.

 

[EDIT] worse is that an inherited property cannot be deleted so I can never see its description.

Share this post


Link to post
Share on other sites
Not sure if this is the right thread but I notice that properties already set are not in the add properties list. So if you want to find out what they do you have to delete them then add them again.

 

[EDIT] worse is that an inherited property cannot be deleted so I can never see its description.

 

You mean inside DR? That's then something I can't fix :) The online documentation should help you a bit but of course I know that having a sep. documentation outside DR is not really optimal :)


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites
Tels, http://bloodgate.com/mirrors/tdm/pub/doc/ does not work for me (I use internet explorer). Only this line at the bottom shows up: © 2008 by ... 0.06 (Tels). Does it work for anybody with ie? Or is it only temporarily unavailable?

 

It is probably subtly broken in IE. Since I am Linux only, I have no way to really test with IE.

 

Do you get any error messages? Which IE do you have? Can you:

 

* try to upgrade your IE unless it is already 7.0

* stop using IE? :)

 

Edit: Here is a link that talks about script debugging in IE, maybe that can help you to get an error message: http://blogs.msdn.com/ie/archive/2004/10/26/247912.aspx

 

Second edit: The current version of the script takes about 1..2 seconds on Firefox and Opera to display the overview page, because it builds extensive views in the background. This might mean that under IE it simple takes an awful longer time to build them (IE and JS are slow), so one option is to wait a minute and see if something else appears. I am eventually gonna fix this by not caching the tabviews before you open them, but not today :)


"The reasonable man adapts himself to the world; the unreasonable one persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man." -- George Bernard Shaw (1856 - 1950)

 

"Remember: If the game lets you do it, it's not cheating." -- Xarax

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Sign in to follow this  

×
×
  • Create New...