Jump to content
The Dark Mod Forums

Some entity properties not listed; which and why


Recommended Posts

Further improvements to the search:

 

* the search query is now entered into the URL, so you can bookmark searches like so:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...tml#search-frob

 

* The search results for spawnargs now also show the spawnarg type

 

* entering special characters lke '(' into the search now works:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...tml#search-(not

 

* the search now also looks into the documented spawnargs, to catch spawnargs with descriptions that are never actually used, like f.i.

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...l#search-immune

 

Have fun :)

"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

Link to post
Share on other sites
  • Replies 249
  • Created
  • Last Reply

Top Posters In This Topic

Top Posters In This Topic

Posted Images

Taking another look at this, very cool! I am not sure I comprehend it all, there's probably a lot I'm missing, so bear with me. :)

 

Say for instance I looked at Undocumented. Is this the full list of undocumented spawnargs in the mod, and thus, those causing the entire problem this thread is indicating? If so, wow, that is massively useful. So I see the first is _color, for example. If I were to go and document that whereever it resides, then it would magically remove it from this list, and, every entity in D3/TDM that can have this property would then display it in the Add Property dialog in DR (as well as on the site)? If so, double-freaking-wow. So say I wanted to document _color. Aside from the obvious (doing a search of local files), does/can the web tool tell me which file it is originally defined in?

 

 

Edit: Hm, I'm guessing 'no' to the second question above, about once documented, having a property show up for every valid entity. This is based on the fact that, for instance, _color appears for light_lamp_desk, even though it is not documented. On the other hand, it doesn't appear for other entities where you'd expect it, for instance, light (what's up with that?)!! As another example, the fact that 'Undocumented!' spawnargs (in pink) show at all for entities suggests the same. If they were assumed not showing because they're undocumented, and that documenting them would cause them to appear magically, yet they already show, as undocumented, then that means the assumption is flawed. :wacko:

 

Unfortunately, that is the main pursuit behind this thread... :unsure: Maybe I'm wrong; can someone point out recent changes? Hm then again that would require me to go back in time and know how the entities were before I have to re-inspect them... maybe I should take out my non-pavlovian lockpicks. (har har)

Link to post
Share on other sites
Taking another look at this, very cool! I am not sure I comprehend it all, there's probably a lot I'm missing, so bear with me. :)

 

No problem :)

 

I'll try to explain a few things. (That should go into a wiki article, I guess)

 

First, note that the "online" documentation as well as the version in SVN are not "life", instead they use a database that is named "devel/doc/js/entities.js".

 

If you want to see when the database was last regenerated, look at the bottom of the online documentation, it says the date when this happened.

 

This database can be done by running the script "devel/inspec.pl" with Perl. You need Perl installed, and possible a few other modules. Get it here:

 

http://www.strawberryperl.com if you are on windows.

 

This means that if you change something in the def files, you need to regenerate the DB otherwise that change is not reflected in the life online documentation!

 

Say for instance I looked at Undocumented. Is this the full list of undocumented spawnargs in the mod, and thus, those causing the entire problem this thread is indicating? If so, wow, that is massively useful. So I see the first is _color, for example. If I were to go and document that whereever it resides, then it would magically remove it from this list, and, every entity in D3/TDM that can have this property would then display it in the Add Property dialog in DR (as well as on the site)? If so, double-freaking-wow.

 

Both questions are answered "Yes", except the need for regenerate the DB for the online documentation so it vanishes from the list :) DR works automatically, but I think you need to restart DR for it to take effect. (Could be wrong).

 

So say I wanted to document _color. Aside from the obvious (doing a search of local files), does/can the web tool tell me which file it is originally defined in?

 

Technically, yes, practically I forgot to include that function. And it is actually not that easy.

Some background info for this (wiki again? :)

 

In our definition files, we have a list of entities. These entities always have two things:

 

* a spawnclass, which defines the underlying C++ code that is responsible for that entity. Examples include idLight, idMoveable etc.

* a list of spawnargs that describe the "options" or "behaviour" for that entity. These get read when an entity is spawned (and some even get read later at run-time) and then influence the entitiy.This set of spawnargs has two basic properties:

 

** it must match the spawnclass. Spawnargs that are not fitting for the spawnclass (or are simple typos) are silently discared. Setting "_color" on a moveable would be such an example of "mismatch", setting "_colour" on a light would be a typo. Both will do nothing.

 

** Spawnargs can be inherited. If an entity has a "inherit" spawnarg, the first thing that is done is getting all spawnargs in the entity pointed to by "inherit" and apply it to the current entity. This means although we just have a flat list of entities, the "inherit" spawnarg makes it effectively a tree.

 

While usually every defined entity could be used in a map, entities that are solely there for providing a set of default spawnargs for entity that inherit from that, are not to be used in a map. In TDM, we usually name them something with "_base" in their name and mark them as "Base class for FOO, do not use!".

 

About documentation:

 

There are three ways to document things in the def files:

 

* comments. Comments can be added anywhere, but they are only visible if you look into the def file manually. This is not helpful for DR users (e.g. mapper), but it can help people who edit the def files themselves. Downside to comments is that they can get outdated, out-of-sync, or just be forgotten :)

* documenting entities is done by adding an "editor_usage" spawnarg on the entity. This should contain a short descripption of that entity and anything that is relevant to the user/mapper. Note that the documentation GUI will show a red remark if this spawnarg is missing, both when you search for entities or when you look at a single entity.

* documenting spawnargs is done with "editor_var name-of-the-spawnarg" lines in the def file. (or editor_bool, editor_int etc.) However, this is really trick.

 

Remember when I wrote above that each entity has a (possible unique) set of spawnargs, and that it can also inherit spawnargs from one other entity? This entity in turn can also inherit spawnargs, and so on, forming an inheritance chain.

 

First, the location of the editor_var spawnarg both matters, and doesn't matter. Lets consider a simple example:

 

We have one base entity, from which everything (should eventually) inherits(s).

 

Now we have two more entities, called "atdm:light_base" and "atdm:moveable_base". These two both inherit from atdm:entity_base .

 

Lets pretend we also have only two actual useful entities, named "atdm:some_light" and "atdm:some_moveable", which both inherit in turn from "atdm:light_base" and "atdm:moveable_base".

 

This forms a small tree that looks like that:

 

post-144-1231179942_thumb.png

 

In this graph, the usable entities are purple, while the base classes are light blue.

 

Now let's assume that both lights and moveables have some spawnargs, and we want to document them.

 

The most important problem: Where to add these documentation lines?

 

The general rule is, as high up in the tree as possible, but not higher. Sounds cryptic? Let me explain :)

 

Let's say that lights have a "_color" spawnarg, and you want to document it. In this case, you could add it to "atdm:entity_base", the highest place in the tree. However, that would mean that this documentation also applies to anything that inherits from "atdm:entity_base", which includes "atdm:moveable_base". However, the Spawnclass for moveables is idMoveable, and this does not support a "_color" spawnarg, hence it should not be documented for them. This would only lead to mappers trying to add such a spawnarg to moveables, wondering what it does and then find out it doesn't do anything, not even causing warnings.

 

So the next logical place would be to document "_color" in "atdm:light_base". This way, every entity that inherits from that entity and is a light, also gets this definition. This means DR will display it in the "Add Property" dialog, and the online documentation will also pick it up.

 

There are, however, two more caveats (nothing is ever simple :)

 

* Just documenting a spawnarg does not mean it will work (see above example with "_color" on moveables) because the mapper can change the spawnclass for an entity and yet the documentation is still (wrongly) there.

* Actually using a spawnarg on an entity is completely sep. from documenting it. You can f.i. document "_color_blah" on "atdm:light_base" but if no entity ever uses it, you get a dangling documentation. (This is even sep. from wether the code for lights actually supports "_color_blah", or not. It can be documented, but not used, but working OR used but not documented, but working OR used and documented and not working etc.

 

Likewise, sometimes we have spawnargs that are defined in a higher up place in the tree than where they are actually documented (the documentation needs moving), or vice versa (this case is okay).

 

We also have the possibility for one spawnclass have the exact same spawnarg as another spawnclass, making two different documentations necessary.

 

As it currently stands, the script generating the database, and the online GUI do not deal with every possible case yet. I tried to keep it simple for a start - as you can see, adding documentation for a few spawnargs needs to be done, anyway :)

 

I hope that answered more questions than it caused :) If you have more questions, please just ask!

"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

Link to post
Share on other sites

I have improved the JS GUI again :)

 

* The entity list now shows the filename where each entity is defined.

 

* Both the documented aswell as the undocumented list of spawnargs (as well as the list of spawnargs on each entity) are a link to a new "spawnarg" tab. This tab shows details about one spawnarg, esp. the type, documentation and a list of entities that actually use that spawnarg, along with the value for each entity. Here is an example:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...rg-acuity_other

 

Hope this is useful :)

 

(Note that the "list of entities that use this spawnarg" is generated by the actual spawnarg name and does not take prefixes into account. E.g. "used_by" would not show entities that use "used_by_1". That's a bug and needs fixing. 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

Link to post
Share on other sites

Btw, I think this answers your earlier question:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...spawnarg-_color

 

;)

 

I'd say we need a new "atdm:light_base" entity, where we can put the documentation on, as well as a good default value.

"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

Link to post
Share on other sites
:wacko: I didn't think about the 'highest possible but no higher' concept; that makes it even more complex to think about. I think I need to just sit down and find some good examples and put them to the test, so I can get some kind of grasp on this and not ask circular questions too much.
Link to post
Share on other sites

Yeah, the entire issue is quite complex. However, I am confident I can write the tools that help people to tackle the documentation.

 

Have you tried the new spawnarg view?

"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

Link to post
Share on other sites

Yep taking a look right now. Hooboy I'm confused. If I look at spawnargs and try to find _color, I can't. I assume this is because it's undocumented. However I find color which I didn't know existed. If I then follow the light link which is provided, I see that light doesn't contain either color or _color. Perhaps the former because it's inherited (the hope is that even those would show), and the latter because it's undocumented. Maybe I do understand afterall, a little...

Link to post
Share on other sites
Yep taking a look right now. Hooboy I'm confused. If I look at spawnargs and try to find _color, I can't. I assume this is because it's undocumented.

 

Yes. I guess some help pages or texts are in order...

 

However I find color which I didn't know existed.

 

Oh, me neither.

 

If I then follow the light link which is provided, I see that light doesn't contain either color or _color. Perhaps the former because it's inherited (the hope is that even those would show),

 

Sorry, forgot to code them in. :)

 

and the latter because it's undocumented. Maybe I do understand afterall, a little...

 

When you follow the "light" link, you are looking at one specific entity. I guess you mean this one:

 

http://bloodgate.com/mirrors/tdm/pub/doc/#spawnarg-color

 

leading to this one:

 

http://bloodgate.com/mirrors/tdm/pub/doc/#...light_flashmine

 

Note that in this case I think the "flashmine" jus has a typo in the spawnarg, I don't think "color" is actually existing.

 

Also, note that the doc says:

 

def/misc.def
42:	 "editor_color color"					"light color"

 

which is I think another typo, it was probably meant to read:

 

"editor_color _color"					"The color of the light in RGB."

 

I guess greebo can say for definite that "color" is wrong and it must be named "_color" and also be documented like that. In that case you just found two bugs in our def files at once :)

 

Edit: Just acked through the code, and yes, it is "_color", not "color", so both the documentation and the one lone usage in the flashmine are wrong. Good catch! Do you want to correct them? :)

"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

Link to post
Share on other sites

When you say,

Sorry, forgot to code them in.

I get confused. Are you adding each of these properties by hand? That is, the script logic isn't parsing them out in some automagical way? Because if it's the former, then human error becomes a big factor, and no one could possibly hope to find all missing things (which goes back to the original problem). :unsure:

 

Good catch! Do you want to correct them?

I don't even understand the whole thing unfortunately. :-/

Link to post
Share on other sites
When you say,

 

I get confused. Are you adding each of these properties by hand? That is, the script logic isn't parsing them out in some automagical way? Because if it's the former, then human error becomes a big factor, and no one could possibly hope to find all missing things (which goes back to the original problem). :unsure:

 

Of course NOT. I was talking about "showing inherited spawnargs" in the following view:

 

http://www.bloodgate.com/mirrors/tdm/pub/d...spawnarg-_color

 

The list shows all entities that have "_color" set. What it doesn't show is:

 

* all entities which inherit one of these set "_color" spawnargs from another entity

* all entities which do not have "_color" set, but which will be forced by the code to use the default value of that spawnarg.

 

Both lists of entities can be possible empty, but they can also contain large lists of entities and it would be good to get an overview over these. It is just I didn't think of it, and when you brought it up, it was way past my bedtime :)

 

The script is totally automatical, but of course someone has to put all the logic in displaying these lists and views into the javascript code :)

 

I don't even understand the whole thing unfortunately. :-/

 

Ow. :( Are my explanations that unclear?

"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

Link to post
Share on other sites

* fixed the "color" description to be for "_color" and fixed the flashmine to have "_color" instead

* teached the parser to keep the line nr info for each entity it parses, this is saved into entities.js by devel/inspect.pl now, and then used by the JS GUI, too :)

* the JS gui now has links to the filenames and display a new tab for the file, this shows all entites defined in that file and on which line they are defined:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...ghts_static.def

 

* the file list displays a count of how many entites are in each file

 

Last but not least I started adding some descriptions to the various tabs and improved the mouse over titles a bit to be more clear.

 

I think the GUI has improved now to be quite useable, so can someone please handle the "Call for help" and post it somewhere visible? :)

"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

Link to post
Share on other sites

Nice work Tels, it works like a charm if you ask me.

 

I think the GUI has improved now to be quite useable, so can someone please handle the "Call for help" and post it somewhere visible? :)

I'm a little busy these days so I don't have time to help with this until next week. You should make this long post a wiki article if it isn't already and point helpers to it.

Link to post
Share on other sites

Over the last days I started to actually use the GUI (and show it off to a few people :) and noticed quite a few issues. First I now fixed quite a lot of spawnarg types in our def files, documented some and removed some typos.

 

In addition, the GUI now has:

 

* links from the search results to the spawnargs and entities

* Any display of spawnarg values now checks what type the spawnarg is, and if it is a color, adds little colored boxes. This can be seen nicely on the screenshot below, or life here:

 

http://bloodgate.com/mirrors/tdm/pub/doc/#spawnarg-_color

 

post-144-1232053487_thumb.png

 

* When linking to a specific spawnarg, the GUI now knows wether that spawnarg is a "base spawnarg", like "used_by", or a variant of it, like "used_by_3". This allows it to display the proper documentation if even you look up "used_by_3" by refering to the actual version without any suffix. Furthermore, this now also works if the spawnarg contains an arbitrary suffix that isn't even mentioned in any entity.

 

Or in other words, if you link to f.i. "used_by_3", you now get the doc for "used_by" AND a list of all entities that use any spawnarg that starts with "used_by". This should help greatly in looking things up.

 

Enjoy.

"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

Link to post
Share on other sites

[transferred from 'itches' thread going off topic]

(subject: name of doc on bloodgate)

 

Yes but TDM consists of a lot more than just entities and materials. I was thinking maybe Dark Mod Entity Reference (Entref for short) but if other types are added then I would say Dark Mod Assets Reference (DMAR) or Dark Mod Resources Reference (DMRR)

 

A candidate for extending it is the models. See my old thread http://forums.thedarkmod.com/index.php?showt...ObjectsList.htm

 

It became rather unworkable as a web page and I was hoping to provide the program but have not had time to progress it. The old zip file is still there for reference though. The main element is keyword index by meaning so if a mapper wanted a chain he could enter 'chain' in your search and hopefully find all the chains in the dungeon folder, plus the ones in doom assets (which I know you want to kill off) plus maybe you could include prefabs which serve a similar function. If a mapper wants a table there are prefab choices as well as models.

Link to post
Share on other sites

Guys, I have to admit, I really don't understand this issue. I think we're still not all on the same page, and I apologize in advance if I'm dense or just 'not getting it', but I'm really not.

 

I wanted to try this out and see if I added documentation, then DR would show the inherited properties on a child class. It doesn't, even with documentation. I chose the simplest case: a func_static (which is documented) and the frobable property (which is also documented; further it is valid for func_static, but not explicitly listed). It doesn't show up for func_static in either the docs or the DR.

 

What am I not getting here? And beyond that, if what I'm not getting is not possible, what is possible behind this effort? Just descriptions for the properties, where ever they might be displayed? That wasn't really my primary concern, at least; I just wanted valid properties for any entity displayed for users as a WYSIWYG helper.

 

---

 

ParentClass has property A

ChildClass has property B

In DR and the docs, User has no idea that ChildClass also supports property A. Yes, they can find out through research, or taking a blind stab at it, but why can't we just show them the inherited property? It's not about documentation apparently (and so back to square one).

Link to post
Share on other sites
Guys, I have to admit, I really don't understand this issue. I think we're still not all on the same page, and I apologize in advance if I'm dense or just 'not getting it', but I'm really not.

 

I wanted to try this out and see if I added documentation, then DR would show the inherited properties on a child class. It doesn't, even with documentation. I chose the simplest case: a func_static (which is documented) and the frobable property (which is also documented; further it is valid for func_static, but not explicitly listed). It doesn't show up for func_static in either the docs or the DR.

 

What am I not getting here? And beyond that, if what I'm not getting is not possible, what is possible behind this effort? Just descriptions for the properties, where ever they might be displayed? That wasn't really my primary concern, at least; I just wanted valid properties for any entity displayed for users as a WYSIWYG helper.

 

---

 

ParentClass has property A

ChildClass has property B

In DR and the docs, User has no idea that ChildClass also supports property A. Yes, they can find out through research, or taking a blind stab at it, but why can't we just show them the inherited property? It's not about documentation apparently (and so back to square one).

 

The "frobable" spawnarg is documented on the entity atdm:frobable_base. This can be seen in the giantic list of "entities"- My apologizes that you cannot see this in any of the other views, like for instance the search results. I didn't know it was important this bit of information.

 

Anyway:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...m:frobable_base

 

inherits from atdm:enity_base while:

 

http://bloodgate.com/mirrors/tdm/pub/doc/i...ity-func_static

 

doesn't inherit from anything, and thus does not inherit the documentation. This is a bit of a dilemma we face here, because technically, you can put *anything* on a func_static, but only _after_ you change its spawnclass to the appropriate class.

 

Or in other words, no you cannot just put "_color" on a func_static, because it might not have the correct spawnclass.

 

* func_static with spawnclass "idLight": "_color" is okay

* func_static with spawnclass "idMoveable": "_color" is not okay

 

I do not know wether "frobably" is something that is inheritent to ALL entities, or only selected spawnclasses. If it is possible for everything, that it:

 

* 's documentation needs simple to be moved to "atdm:entity_base"

* func_static (and every other D3 entity class thats left dangling) must inherit from "atdm:entity_base"

 

Apart from the fact that not all documentated spawnargs are atm in the right place (please bear with us, we are working on improving the doc!), there is also the problem that very generic entities like "func_static" mioght have a documented set of spawnargs, but this can change totally based on the spawnclass. AFAIK, DR does not really take this into account.

 

I hope this clears this up :)

"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

Link to post
Share on other sites
I think I follow what you're saying. So it wasn't really a valid test; I'll have to find another (which is actually not too easy, like stabbing in the dark). BRB ASAP (whenever that is) :).

 

:)

 

Expanding on my post above, "func_static" and all the others should really inherit from "atdm:entity_base" to get the relevant documentation. Can somebody please do this?

 

Instructions:

 

* add "inherit" "atdm:entity_base" to all entities that do not have "inherit" yet.

"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

Link to post
Share on other sites
Expanding on my post above, "func_static" and all the others should really inherit from "atdm:entity_base" to get the relevant documentation. Can somebody please do this?

I can do this now, I'll be changing some def files then within an hour or so.

Link to post
Share on other sites
Done! Changes committed to 37 def files.

 

Very cool, I regenerate entities.js and upload it in a minute.

"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

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.


×
×
  • Create New...