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. :)

Share this post


Link to post
Share on other sites
I am not entirely sure what you mean by "not listed at all".

What I mean is pretty much the confusion cloud that has been surrounding this issue for literally years at this point: that in many cases, not every possible property of a given entity is shown; in fact it seems in most cases, most are not shown.

 

An example (among many given over the years) off the top of my head: new user comes a long and creates a func_static. Can it have frobable? Sure. Can it have _color? Hmm, I don't know for sure. Rotation? Don't know. Health? Possibly... but that might need further properties that define it as destructible, etc. Can it have a sound? How is a script added to it? Is S/R an option? What about particles? Etc X 1000 .........................

 

I'm not really asking the questions above, I'm trying to make the point: the goal is and always has been (for years now) to have EVERY single possible property listed for EVERY single entity in the game. When I originally said there'd need to be a "programmatic solution", I really did mean it: there is no way any human or army of humans could go through the entire list of entities and by hand add all properties for every item; it would have to be handled by a script or program. Somehow. I know we (Tels and I) have butted heads a bit on this issue before, as you were mentioning that if it's not documented, it's pointless to include it, but I could not disagree more strongly. Documenting is vital, yes, but it is secondary to actually including the properties AT ALL. We're going to have thousands of new users wondering what they can do, what they can pull off by clever jury rigging and innovation, but if the parameters are not even in front of them ("Hm, health on a crate? Interesting..."), they stand small chance at achieving much.

 

Summary: every single valid property for every single entity, regardless of whether it is inherited or unique to that entity.

 

Hopefully this example finally indicates the point better. :)

Share this post


Link to post
Share on other sites
Summary: every single valid property for every single entity, regardless of whether it is inherited or unique to that entity.

 

Agreed. You could pretty much do this in the TDS editor....limited as it was....and have sexy results.

Share this post


Link to post
Share on other sites

I agree with you Dave. It's really helpful for mappers to have all possible properties for entities in front of you like in DoomEdit. Why not use something similar as the DoomEdit entity inspector. It shows all properties in a list, all you need to do is give them a value and they become active.

Or the add-property menu could have all properties listed.

Share this post


Link to post
Share on other sites

Well, I agree about the need to have this documented, but I'm sceptical about the script doing all the work automatically. Some spawnargs are indexed (S/R spawnargs or conversation spawnargs), some have the name of other entityDefs in them (they are sort of "dynamic").

 

What a script can do is to parse the existing entityDefs (like Tels already did), and to parse the ::Spawn() methods of the actual entities in the game code. But this still doesn't give you all the possibilities, as some spawnargs are not queried in the ::Spawn function, but somewhere else in the game code.

 

What I'm trying to say is: if you're waiting for a script to create the perfect documentation source for mappers, you will wait a long time. You can reach perhaps 80% of the spawnargs, but a good percentage must be done manually.

 

And I'm not even talking about a description here - you need a human to formulate a proper English sentence to describe what the spawnarg is going to do. How is a script going to do that?

Share this post


Link to post
Share on other sites
What I mean is pretty much the confusion cloud that has been surrounding this issue for literally years at this point: that in many cases, not every possible property of a given entity is shown; in fact it seems in most cases, most are not shown.

 

I think you are completely confused :P

 

What I mean is that once a spawnarg is documented in the def file, the editor will automatically include and show it. No documentation => no show. Documentation => show. :)

 

That is why documenting them in the def file is so important. Once it is documented, everything else follows.

 

(And I think it would be silly to just include them all in the editor without at least a 5 word explanation what they do :)

 

There are of course exceptions. While it would be technically possible for the editor to list every spawnarg on every entity, this would not make sense, because the spawnarg must also be suppored in code. Trivial example, setting _color on a non-light entity will not do anything, so it is pointless to show the possibility to the mapper.

 

However, we can (and do) fix this by documented _color only on entity that inherit from idLight, and the editor then knows when to show the spawnarg and when not.

 

So, once more: document the spawnargs, the rest should follow.

 

@greebo:

 

I am not suggesting automatically documenting the spawnargs. If I could write a program to do this, I wouldn't bother wasting time working anymore - I would roll in money :P

 

What my script is supposed to do is to show which spawnargs miss documentation, have wrong documentation or double documentation. We then can fix this manually.

 

Currently we even don't have (had) a good overview what is actually undocumented. :)

 

An example (among many given over the years) off the top of my head: new user comes a long and creates a func_static. Can it have frobable? Sure. Can it have _color? Hmm, I don't know for sure. Rotation? Don't know. Health? Possibly... but that might need further properties that define it as destructible, etc. Can it have a sound? How is a script added to it? Is S/R an option? What about particles? Etc X 1000 .........................

 

Please note that as greebo said, we also have a host of spawnargs where one set spawnarg must be followed by other spawnargs, and sometimes these can (and must) be indexed. That makes it even more complicated.

 

However, I propose we start small and start documenting first the undocumented spawnargs.

 

Summary: every single valid property for every single entity, regardless of whether it is inherited or unique to that entity.

 

I hear you, but as I wrote, this is not easy, and a lot of work. But the good news is, we are on it, and you can help - just document a missing spawnarg each day :)


"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
What a script can do is to parse the existing entityDefs (like Tels already did), and to parse the ::Spawn() methods of the actual entities in the game code. But this still doesn't give you all the possibilities, as some spawnargs are not queried in the ::Spawn function, but somewhere else in the game code.

 

All spawnargs that are possible parsed by the code should also all be documented in the def file.

 

If the spawnarg is actually used somewhere, but is undocumented, this will be noticed because the script will complain.

 

If the spawnarg is not used anywhere, well, then we have a problem. But I am not sure this is actually the case and even if, if it is important.


"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 agree with you Dave. It's really helpful for mappers to have all possible properties for entities in front of you like in DoomEdit. Why not use something similar as the DoomEdit entity inspector. It shows all properties in a list, all you need to do is give them a value and they become active.

Or the add-property menu could have all properties listed.

 

That's actually how it already works :) We are here just discussing the minor detail why some of the properties are not shown and how we best fix it :)


"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 think you are completely confused

Am I? I would think if my assertion was wrong (and at least understood by readers) it would've been indicated some time in the last year of saying it. Instead, this issue continues to be encountered, posted, tracked, and discussed, over and over and over, without resolution. As recent as just a few days ago it was confirmed/indicated that this is not DR's fault.

 

No documentation => no show. Documentation => show.

This is not true (or we're using different terms). There are plenty of properties displayed in the editor which provide no descriptions. It is not required in any way.

 

And I think it would be silly to just include them all in the editor without at least a 5 word explanation what they do

1. not when there might be thousands

2. not when doing so will delay users being able to even see the properties for years or ever.

 

There's a time when you have to decide: do we hold onto a purist view of all or nothing, or at least provide as much as we can manage.

 

While it would be technically possible for the editor to list every spawnarg on every entity, this would not make sense, because the spawnarg must also be suppored in code. Trivial example, setting _color on a non-light entity will not do anything, so it is pointless to show the possibility to the mapper.

I'm not talking about every spawnarg for every entity. I'm talking about every applicable spawnarg for every entity. This quote makes my point exactly: if _color is not on an entity (and the listing is unabridged), the mapper will know it is not applicable. Conversely, if the property does exist, they'll know they can make use of it. This is exactly my point.

 

So, once more: document the spawnargs, the rest should follow.

You forgot a step: document, wait years or forever, the rest should follow.

Despite the fact that some properties are already displayed without descriptions...

 

You can reach perhaps 80% of the spawnargs, but a good percentage must be done manually.

What is perplexing from the outside is: if the game knows all that can be done (e.g., all possible properties on an entity), why can't we list all of those properties? Does it require game engine logic to determine them?

 

For the record, I've never cared about the descriptions much. That's Tels' bag, and it's obvious that someone must write them for them to exist. I am only arguing for the sake of displaying the properties at all. Without knowing them, our users are fumbling blind.

Share this post


Link to post
Share on other sites
This is not true (or we're using different terms). There are plenty of properties displayed in the editor which provide no descriptions. It is not required in any way.

That's where I think you're confusing issues - define what you mean by "displayed in the editor", as I think we might be talking about different issues.

 

Just being listed in the Entity Inspector is not the same as being displayed in the "Add Property" dialog. For the former it's just necessary to be defined on the entity(def), the latter requires a proper "editor_var" documentation spawnarg.

 

What is perplexing from the outside is: if the game knows all that can be done (e.g., all possible properties on an entity), why can't we list all of those properties? Does it require game engine logic to determine them?

If you were a coder (or could read the game code) you surely would understand. There is no list of all properties in the game code or some such thing. The code is requesting certain spawnargs on a case-by-case basis (i.e. something like spawnArgs.GetBool("auto_setup_double_door", "1");). Some spawnargs are not referenced directly as string (like this example, which would be easy to parse), some are queried by passing other variables, or calculated string values.

Share this post


Link to post
Share on other sites

Okay basically just that in the picture shown below, every single possible property (according to current game code/state) any mapper could ever apply to that entity would be displayed in that box, somewhere. I frankly don't care (much) about the descriptions; they are secondary in my opinion, really only needed once or until a mapper understands what the property does.

 

The fear (confirmed apparently) is that a great many are simply not shown to the user at all; ones that are inherited from id classes, or for whatever other reason (missing keys or whatever).

 

The code is requesting certain spawnargs on a case-by-case basis

Does that mean the game can just error out if it encounters an invalid property on something?

post-58-1228407976_thumb.jpg

Share this post


Link to post
Share on other sites
Does that mean the game can just error out if it encounters an invalid property on something?

The game will only emit a warning if a spawnarg contains invalid values or is needed but missing. You can add any spawnarg with any name, the game won't care about le't say "blah" "fricking unimportant value".

 

I guess we're basically agreeing in some way. We need to list spawnargs that are understood by certain entities. However, I disagree with your opinion that it must/can be done by a script. A script cannot cover all cases, documentation is and stays a manual task to be performed by humans.

Share this post


Link to post
Share on other sites
The game will only emit a warning if a spawnarg contains invalid values or is needed but missing. You can add any spawnarg with any name, the game won't care about le't say "blah" "fricking unimportant value".

 

I guess we're basically agreeing in some way. We need to list spawnargs that are understood by certain entities. However, I disagree with your opinion that it must/can be done by a script. A script cannot cover all cases, documentation is and stays a manual task to be performed by humans.

 

As greebo said. There is no list of "what spawnarg is applicable to this entity class". (I also agree on that this can be done automatically. Even I would shudder writing a script for that. It is much faster doing it manually).

 

Or actually, there is such a list, it is build manually by adding "editor_var blah" "blah" descriptions in the def files.

 

That is the weakness of the D3 entity parser. It doesn't care if you add a spawnarg "blah blub", it just parses it by some rules and if it looks okay, it accepts. Wether the actual C++ code then actually _works_ with that spawnarg, or just ignores it, that does the def parser (nor the editor) not know.

 

Let me show you an example:

 

entityDef atdm:foo {
 "inherit" "func_static"
 "foo" "1 2 3"
}

 

Above is a valid entity. The "foo" however, will do nothing. And the user will never be shown "foo" in the editor under the "Add properties" dialog.

 

Now if we actually add support in the C++ code for the "foo" spawnarg, then the entity above would "work". However, the editor still won't show it under "Add Properties". So we need to modify the entity def:

 

entityDef atdm:foo {

"inherit" "func_static"

"editor_var foo" "A color value of blah."

"foo" "1 2 3"

}

 

Then the editor knows that:

 

A: foo is a valid spawnarg for all atdm:foo and inherting entities

B: What description to show to the user

 

As I wrote earlier, there is really no other option as to add the "editor_var etc" lines to the entity defs. Because if you just show *every* spawnarg for *every* entity, you show also spawnargs that are not applicable (as Sneaksy also noted :)

 

However, since the neither the game code nor the editor actually *know* which spawnarg applies where without us telling it, we need to tell it this by adding the appropriate "editor_var foo" lines in the relevant def files.

 

I hope that you don't mind that I repeated the above for you:

 

We need to tell the editor which spawnarg applies where by adding the appropriate "editor_var foo" lines in the relevant def files. :)

 

As for the actual task, I am on it. But before we add the documentation, I wanted to get an overview on what is actually missing. So the plan is:

 

* get an overview (almost done, we have a script for it now)

* add the documentation to spawnargs (You can do this even now. Nobody stops you. Just do one a day. :)

* Be happy and dance.

 

As greebo said, there is no other way than manually adding the relevant documentation and tagging spawnargs manually because neither the game nor the editor actually do know (or care) which spawnarg can be applied where.

 

I know it is frustrating to "discuss" and "debate" this issue while nobody does the actual work on adding the spawnargs docs.

 

But my days only have 24h here and I am spending already a large junk of my holiday time on TDM. Perhaps I should have just flown to an island in the carribian or something.... In any event, *anybody* can document spawnargs. You don't need to code, know how to code, or write scripts. Just add documentation to the def files </broken record> :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
As greebo said, there is no other way than manually adding the relevant documentation and tagging spawnargs manually because neither the game nor the editor actually do know (or care) which spawnarg can be applied where.

 

I know it is frustrating to "discuss" and "debate" this issue while nobody does the actual work on adding the spawnargs docs.

 

But my days only have 24h here and I am spending already a large junk of my holiday time on TDM. Perhaps I should have just flown to an island in the carribian or something.... In any event, *anybody* can document spawnargs. You don't need to code, know how to code, or write scripts. Just add documentation to the def files </broken record> :P

 

All right then, lets get on with it. You can assign a group of entities to me, I'll be happy to help.

Share this post


Link to post
Share on other sites

Well, this sounds like an offer, doesn't it? :)

 

Are you able to read C++ code? It's not actually necessary, but it helps.

Share this post


Link to post
Share on other sites
Well, this sounds like an offer, doesn't it? :)

 

Are you able to read C++ code? It's not actually necessary, but it helps.

 

There are also quite a lot of spawnargs where the function is "obvious", like "frobable" etc. So you might even be able to document them without C++ code reading :)

 

Btw, the following list variable types is what I know is used:

 

* float

* bool

* int

* string

* model

* color (only used twice)

* material

* gui

* var (a generic variable, I am not sure what the difference to "string" is)

 

Choosing the appropriate variable type helps the editor to restrict the user input,too :)

 

Also note that you don't need to document each spawnar on each entity, inherited spawnargs also inherit the documentation.

 

You can check here http://bloodgate.com/mirrors/tdm/pub/doc/entities.html which spawnargs are not yet documented, but please not that:

 

* There is not yet a list of the undocumented ones, so you need to click entities and see which are red

* you need to document them in en "uppermost" entites, so the ones inheriting from it inherit the doc, too. That is a bit tricky, as you need to manually look where the doc should go (root class is probably a safe choice).

 

PS: Thanx for helping :)


"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

Reading it shouldn't be a problem.

 

Why not make a new 'Help request' thread for this and ask people to do a group of entities. I'm not going to do them all alone! I can do the loot entities :) to start with.

Share this post


Link to post
Share on other sites
Reading it shouldn't be a problem.

 

Why not make a new 'Help request' thread for this and ask people to do a group of entities. I'm not going to do them all alone! I can do the loot entities :) to start with.

 

Because until very very recently, we didn't really know which spawnargs need documenting (thats why I wrote the script :P

 

Also, note that you only need to document each spawnarg _once_ not for every entity (just in case that wasn't clear :)


"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
Also, note that you only need to document each spawnarg _once_ not for every entity (just in case that wasn't clear :)

 

Yeah got that. So, to get it straight, what I should do for loot_base is this:

search for atdm:loot_base in your entity documentation. For each spawnarg that has no description and that is not inherited add something like

"editor_var snd_acquire" "Sound that is played when the loot object is acquired."

to atdm:loot_base in the def file.

Share this post


Link to post
Share on other sites

Yes, a help request makes sense. I'll do that as soon as you finished your first round, to see what actually needs doing. This way you can gain a bit of insight and explain the steps to others who are willing to help.

 

Thanks anyway for your offer, mappers will surely appreciate this.

 

There is also one more editor_* flavour, I think it's only used for D3 entities so far: editor_snd (for soundshaders).

 

As for the loot entities: these are deriving from atdm:moveable_base, if I recall correctly? So each spawnarg which is referring to functionality coming from idMoveable, the appropriate spawnargs need to be added to the atdm:moveable_base entityDef. I guess you'll figure that out anyway.

Share this post


Link to post
Share on other sites

Okay this sounds like it's going somewhere. Please humor me on this, but I want to make sure all is clear and that I'm understanding it (if I do I might be able to help as well):

 

If editor_whatever fields are added, and (at least optimally) descriptions, then they will automagically appear in the editor for whatever classes they affect? Or is there more work to do?

 

Example:

Base_class_1 has a property "whatever" and value "something"

Child_class_1 inherits from Base_class_1

Flanders goes in and adds a key pair for Base_class_1...

 

Does Child_class_1 now display that property in the editor? (yay!) Or must it be manually added for Child_class_1 as well? (nightmare!)

 

 

Edit: Also, would this mean extracting all id def files and modifying them all to include these?

Share this post


Link to post
Share on other sites
Does Child_class_1 now display that property in the editor? (yay!) Or must it be manually added for Child_class_1 as well? (nightmare!)

The answer is yay. DarkRadiant takes care that editor_* spawnargs are inherited.

 

Edit: Also, would this mean extracting all id def files and modifying them all to include these?

Yes, partially. But most id entities are meaningless to us anyway, we already override the most important files in TDM (func.def, trigger.def, aas.def and path.def, etc.).

Share this post


Link to post
Share on other sites
There is also one more editor_* flavour, I think it's only used for D3 entities so far: editor_snd (for soundshaders).

 

Ah fixed my script and updated the online doc. (It is still static for now)


"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 understand a script cannot add descriptions, but can the script be made so that when it cannot find a description and the spawnarg is not inherited it adds to the def file:

 

"editor_var <spawnarg_name>" ""

 

That way, we don't have to search the entity document each time to find out what we should add and we only have to type a description between the two quotation marks.

Share this post


Link to post
Share on other sites
I understand a script cannot add descriptions, but can the script be made so that when it cannot find a description and the spawnarg is not inherited it adds to the def file:

 

"editor_var <spawnarg_name>" ""

 

That way, we don't have to search the entity document each time to find out what we should add and we only have to type a description between the two quotation marks.

 

I already rewrote the script to generate Javascript from the entity def files, as well as a stub JS to list/show etc. the existing documentation. Currently working on actually showing the content. My idea was that undocumented spawnargs get listed on some sort of list-overview, along with an entity where they are first used as well as the file/linenr that happens.

 

However, it might be a good idea to automatically insert empty descriptions. But before I spent a few hours coding that in, lets first see how many spawnargs we are actually talking about. I guess it might not even be more than a dozend :)

 

Also, a human would need to determine the type, so it can't be automated much, anyway.

 

In any event, I am on it, please allow me a few more hours :)


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