Some entity properties not listed; which and why

[Tels]

Ah, I often even forget, because all of you guys speak such perfect English. I've always wondered what it's like to be fully bilingual (and I seem to always get involved with bilingual women for some reason... hm, maybe I should move to Europe), but I don't think I'll ever know.

 

I only ever notice my bad English when I stumble over subtle points like the one above Meaning, almost every hour hehe But there are also cultural difference to consider, these are often easily forgotten with the internet blurring the line between someone next door, and someone being in Australia

 

As for the woman, well, maybe we should swap places

 

Well crap. I assume we would need the id ones, too... but if they're already packed up, can their definitions be affected without repacking everything? Perhaps a sort of addendum def to the existing packed files? That was actually 50% of my concern, and probably 75% of what I run into in general mapping use -- undocumented id properties.

 

This is no real problem, if we add a simple "editor_var foo" "barbaz" in our def files, it will be documented automatically.

 

The only real problems right now are:

 

* find out which are undocumented yet

* document them

 

The first one I am about to automate. The second one will be a bit of work, tho.

[SneaksieDave]

Where did this leave off, specifically the automation of the first step (just determining which props are not shown and showing them)? I just ran into this for the umpteenth (whoa, spellcheck doesn't dislike that; ironically it does dislike "spellcheck") time, at random, simply trying to help someone with a speaker problem on the editing forum. I saw that some of the speakers I placed in rain.map have some properties, e.g., s_justVolume and s_leadthrough, that don't show up in entity lists at all (not Add Properties, not the Entity Tree, even). Of course there is also no description which magnifies the problem, but the first issue is, they're not listed at all; how is a user to know they even exist, to use them, or seek a definition? Further, the speaker 'blue/specialized' folder is empty, so I imagine that might be part of the problem. The small number of properties available in Add Properties indicates this is a pretty large problem.

 

To be sure, I do realize your feeling is that without documentation, simple listing of the properties is of little use, but I'm saying it's at least a needed first step. I wouldn't -- and couldn't -- even know these properties exist, in current state. There are surely a great many more across all entities.

[greebo]

Are you saying the entities are missing their "editor_var blah" spawnargs completely? If yes, there's nothing DarkRadiant can do about. If they are there, then there's probably a bug and I need to be pointed to the ones that are actually missing.

[SneaksieDave]

I haven't fully understood the issue, only reporting from a user's perspective, so I'm not sure (fully) where fault lies. I thought maybe Tels had some progress with the script he was talking about. From my perspective, nothing's changed from the first post, except that I've run into more unexpected cases of it. In fact it seems I run into it any time I use an entity I don't usually visit (familiar cases being overlooked), which leads me to believe this occurs virtually everywhere.

 

For this specific case (not looking for a specific fix though, rather an all encompassing solution that once and for all puts this beast to rest), I would imagine s_justVolume and s_leadthrough are id-specific values, so that's (yet another) reason they don't show up. From outside the box, it seems the issue might be one or more of:

 

- missing entries in TDM files (yes)

- missing entries in Doom3 files (yes)

- possible bug in DR (no direct evidence at this time)

- who knows what else

[Tels]

I haven't fully understood the issue, only reporting from a user's perspective, so I'm not sure (fully) where fault lies. I thought maybe Tels had some progress with the script he was talking

about.

 

Sorry no

 

(The script is under devel/inspect.pl and I wanted to teach it to show definitions with no editor_var entries)

[SneaksieDave]

Just the monthly ping to see if this has any new hopes? Ran into another issue where a spawnarg which was not made visible to the mapper would have solved the problem.

 

Again I'll say, damn the descriptions; the first step is seeing the spawnargs at all (e.g., "nopush" is fairly self-evident), and worrying about descriptions can come later. It's not a good reason for this never to find resolution.

[OrbWeaver]

It's been a while since I looked at the entity code (or anything else to be honest) but I can do some debugging if it is causing serious problems.

 

That is, assuming that it is actually a DR problem: has this been determined, or is this looking like a problem with the DEF files missing values?

[SneaksieDave]

I believe it's the latter, but I could be wrong. Last we left off, Tels was writing a script that will troll through and find all fields on all entities which don't contain 'editor_var'. I think. If finding and correcting those results in all relevant fields for every entity, whether inherited or defined specifically for that class, showing in the editor "Add Property" lists (the goal), then it is in fact not a DR problem.

 

I think.

 

 

--------

Edit: For recap's sake, the simplest example (of thousands) of the problem I can think of:

create a func_static -> Add Property -> where is frobable ?

 

It's a valid property for the entity, and obviously very important to TDM, but it is not shown to the user. Now think of the countless cases where this happens, and that often the user will not even know they exist, let alone know they are valid properties to choose.

 

The hope is that every entity, id or TDM, would show every property which applies to it (even if most of them are stuffed into some 'less important' folder or something).

[Komag]

The hope is that every entity, id or TDM, would show every property which applies to it (even if most of them are stuffed into some 'less important' folder or something).

 

Yes indeed, I have wished for this often, not knowing what things could be done with a door for example.

[greebo]

I can raise the severity of the issue report, so that it will get looked into next. I'm currently working on the Namespace refactor (still), and because I can only do little steps while I'm at work it takes longer than I wish it would. I'm already two thirds through with the redesign, and it looks quite good so far.

 

edit: Reopened: http://bugs.angua.at/view.php?id=443

[angua]

I can confirm that there are spawnargs that are not visible in DR (both when clicking on "add spawnarg" and in the inherited properties) even though they are defined as editor_var in the def. I think one of them was door_handle for doors. It might be that they are visible in the entity browser though (entity menu on menu bar)

 

I'm pretty sure that there are still some spawnargs used in the code that aren't documented in the defs at all.

[SneaksieDave]

Interesting, I was assuming it was now all about missing defs, but I guess DR does play some role in it; thanks for determining that. I can further confirm that some items are in fact not listed in the entity class tree either (as in the example: func_static, frobable). And of course that some are simply not documented.

 

So it looks like we've got a bit of a puzzle here afterall.

[SneaksieDave]

I have reluctantly recycled the issue again, as it looks like it is ongoing (see latest note in issue).

[greebo]

I already added a note to the tracker entry, but I put it here as well: can you give me a specific example of an editor_var spawnarg that is correctly defined in the entityDef, but is missing in the Add Property dialog?

 

I need something specific to look into, a generic nope, doesn't work doesn't exactly help me.

[SneaksieDave]

I mentioned examples in the defect note, but I'll include them here:

 

* func_static (class itself shows almost nothing inherited): frobable (assumed should appear on everything; originally mentioned above, here)

 

* atdm:ai_builder_guard: health (is listed as inherited; is not listed in Add Props)

in contrast to acuity_vis (is listed as inherited, and in Add Props -- why the different treatment?)

 

* atdm:mover_door: snd_close

 

etc. There are many more examples but finding them is trial and error until reasons are determined.

 

So far I've intentionally resisted getting too specific as to particular missing items, in an attempt not to foster per-case fixes. The evidence suggests this is a multi-faceted thing extending to potentially hundreds of missing properties, and would be near impossible to fix by hand, one at a time. I assumed the confirmation and reasons above by angua and Tels were sufficient guidance to find the true reasons behind the problem, sorry.

[greebo]

Ok, I'll check them out.

[greebo]

I could look into this tonight:

 

* func_static (class itself shows almost nothing inherited): frobable (assumed should appear on everything; originally mentioned above, here)

The "frobable" property is originally defined on the atdm:frobable_base entity (also as editor_bool doc spawnarg).

 

func_static does not inherit from atdm:frobable_base, hence it does not list the option, as the editor_bool frobable spawnarg is not defined on func_static.

 

* atdm:ai_builder_guard: health (is listed as inherited; is not listed in Add Props) in contrast to acuity_vis (is listed as inherited, and in Add Props -- why the different treatment?)

Same here, there is no editor_var health spawnarg to tell the entity inspector to show the option on "Add Property".

 

Note that simply inheriting a spawnarg isn't enough to have it included it in the "Add Property" dialog. It must be documented as "editor_yyy" variable.

 

* atdm:mover_door: snd_close

Ditto.

[Tels]

I could look into this tonight:

The "frobable" property is originally defined on the atdm:frobable_base entity (also as editor_bool doc spawnarg).

 

func_static does not inherit from atdm:frobable_base, hence it does not list the option, as the editor_bool frobable spawnarg is not defined on func_static.

Same here, there is no editor_var health spawnarg to tell the entity inspector to show the option on "Add Property".

 

Note that simply inheriting a spawnarg isn't enough to have it included it in the "Add Property" dialog. It must be documented as "editor_yyy" variable.

Ditto.

 

Is this purely a case of "editor_xyz abc" missing in our def files in these specific cases?

 

If I find time on the weekend, I can whip up a script that outputs a list of these spawnargs, so we can add them.

[greebo]

Yes. The cases above are not a DarkRadiant bug, the spawnargs are simply not set up as editor variables.

[SneaksieDave]

Okay then it sounds like that's a new tracker entry. I will tentatively assign to Tels(?).

 

I'll leave the original entry (the one indicating the problem, and asking the source) open as a test bed for when/if this need is addressed.

[Tels]

Okay, I started working on this (actually, worked all afternoon on it phew).

 

First thing I did is modify the devel/inspect.pl script to generate HTML documentation for the entities and their spawnargs.

 

Currently, the script generates static HTML pages with a class view, a full list of all entities, and one page for each entity.

 

Since that generates over 6Mbyte in over 1000 files, I have not checked the resulting files into SVN

 

If you want to view them, you can either:

 

* run perl devel/inspect.pl yourself and then browse the devel/doc folder

* download the compressed documentation (2Mbyte!) from:

http://bloodgate.com/mirrors/tdm/pub/tdm_doc.rar

* Browse it online at:

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

 

As I wrote above, currently the HTML is static. Advantage is that it doesn't need Javascript enabled, but it makes for huge lists and I eventually plan turning it into an interactive page. But that's for another day.

 

Things done:

 

* show inherited status for spawnargs on each entity

* show documented status for each spawnarg (no overview over undocumented yet)

* show class list and entity list

* render graph view (unfortunately too big)

 

Things todo:

 

* for each entity, show a better overview (editor_usage, inherit, and a list of entities that inherit from that one, in which file it was defined etc.)

* make nicer, clickable spawnargs (for instance for colors, models, scripts etc.)

* show the original, unmodified text for this entity from the def file

 

Plenty to do

 

Now, if someone wants to improve the documentation, go to the def files, and add text for instance for "frob_action_script" etc.

[Tels]

Here is a screenshot of an example page:

 

[SneaksieDave]

Holy cow. Tels you scripting freak.

 

Is this going to (eventually) cover properties that aren't listed at all? I'm assuming it doesn't yet, because some things have only a small handful.

[Tels]

Holy cow. Tels you scripting freak.

 

Well, I re-used the D3 entity parser and graph tool I already wrote, so it wasn't that much work (anymore

 

Is this going to (eventually) cover properties that aren't listed at all? I'm assuming it doesn't yet, because some things have only a small handful.

 

I am not entirely sure what you mean by "not listed at all". Do you mean spawnargs that are used only once (and thus hint at typos?). The lines in red show spawnargs which have _no_ "editor_var something" in any definition (it is not only respecting inheritance, but looking at all other entities, too!). These need adding as a first step.

 

(For instance "frob_action_script" would need an "editor_var frob_action_script" "blah blah" somewhere).

 

There are a few ideas I had about listing in nice overview pages:

 

* spawnargs which have no editor_(var|int|float|...) descriptions (these need documentation)

* spawnargs which have multiple editor_(var|int|float|...) descriptions (these need correcting so only one is used)

* editor_foo descriptions which are not reflected in spawnargs at all (spawnarg was removed?)

* editor_var descriptions (these should be replaced by more specific editor_bool etc)

 

etc. But run out of time for today and will now go to the movies

[Tels]

Note to myself:

 

In inheritance chains, foo => bar => baz, and blah => blub => bluh, two different descriptions for a spawnarg can exist,these would hint at one and the same spawnarg doing different things, depending in which chain it is encountered. For instance, "foo" could mean " a value of foo" for all idFoo entities, and "some other value of foo" for all idBaz entities. Need to take this into account.