help request: property descriptions

[Flanders]

def/aas.def

def/animations_reference.def

def/bc_misc.def

def/d3_junk.def

def/env_simplevehicle.def

def/func.def

def/misc.def

def/moveable.def

def/path.def

def/portal_sky.def

def/tdm_absencemarker.def

def/tdm_ai_animal_horse.def

def/tdm_ai_animal_rat.def

def/tdm_ai_animal_raven.def

def/tdm_ai_base.def

def/tdm_ai_builder_forger.def

def/tdm_ai_builder_guard.def

def/tdm_ai_builder_inquisitor.def

def/tdm_ai_builder_priest.def

def/tdm_ai_citywatch.def

def/tdm_ai_citywatch_elite.def

def/tdm_ai_elemental_fire.def

def/tdm_ai_ghostwoman.def

def/tdm_ai_head_base.def

def/tdm_ai_heads.def

def/tdm_ai_heads_dev.def

def/tdm_ai_heads_springheel.def

def/tdm_ai_houseguard.def

def/tdm_ai_humanoid.def

def/tdm_ai_humanoid_undead.def

def/tdm_ai_inventor_engineer.def

def/tdm_ai_merc_elite.def

def/tdm_ai_merc_proguard.def

def/tdm_ai_monster_base.def

def/tdm_ai_monster_belcher.def

def/tdm_ai_monster_spider.def

def/tdm_ai_monster_werebeast.def

def/tdm_ai_nobleman.def

def/tdm_ai_noblewoman.def

def/tdm_ai_pagan_female.def

def/tdm_ai_steambot_lantern.def

def/tdm_ai_thief.def

def/tdm_ai_townsfolk_beggar.def

def/tdm_ai_townsfolk_commoner.def

def/tdm_ai_townsfolk_thug.def

def/tdm_ai_undead_revenant.def

def/tdm_ai_undead_skeleton.def

def/tdm_ai_undead_zombie.def

def/tdm_ai_undead_zombie_short.def

def/tdm_ai_vocal_sets.def

def/tdm_ai_weapons.def

def/tdm_ammo.def

def/tdm_banners.def

def/tdm_base.def

def/tdm_bloodmarker.def

def/tdm_conversation.def

def/tdm_damage.def

def/tdm_debugging.def

def/tdm_deprecated.def

def/tdm_difficulty.def

def/tdm_difficulty_default.def

def/tdm_frobable.def

def/tdm_func.def

def/tdm_furniture.def

def/tdm_healing.def

def/tdm_inventory_loot.def

def/tdm_inventory_map.def

def/tdm_items.def

def/tdm_keys.def

def/tdm_lights.def

def/tdm_lights_static.def

def/tdm_liquid.def

def/tdm_loot.def

def/tdm_maps_blackheart_manor.def

def/tdm_maps_gathers.def

def/tdm_maps_saintlucia.def

def/tdm_melee.def

def/tdm_moveable.def

def/tdm_moveable_containers.def

def/tdm_moveable_decorative_vases.def

def/tdm_moveable_food.def

def/tdm_moveable_furniture.def

def/tdm_moveable_hangers.def

def/tdm_moveable_junk.def

def/tdm_moveable_kitchen.def

def/tdm_moveable_kitchen_utensils.def

def/tdm_moveable_lights.def

def/tdm_moveable_loot.def

def/tdm_moveable_musical.def

def/tdm_moveable_readables.def

def/tdm_moveable_rocks.def

def/tdm_moveable_tools.def

def/tdm_moveable_weapons.def

def/tdm_moveable_wearable.def

def/tdm_mover_base.def

def/tdm_mover_button.def

def/tdm_mover_doors.def

def/tdm_mover_elevators.def

def/tdm_mover_lever.def

def/tdm_music.def

def/tdm_objects_ragdoll.def

def/tdm_player_thief.def

def/tdm_playertools.def

def/tdm_playertools_flashbomb.def

def/tdm_playertools_flashmine.def

def/tdm_playertools_lantern.def

def/tdm_playertools_lockpicks.def

def/tdm_playertools_mine.def

def/tdm_projectiles.def

def/tdm_prop_items.def

def/tdm_prop_wearable_items.def

def/tdm_propagated_sounds.def

def/tdm_readable.def

def/tdm_response_effects.def

def/tdm_rope.def

def/tdm_shopitems.def

def/tdm_soundprop.def

def/tdm_target.def

def/tdm_team_relations.def

def/tdm_weapon_arrow.def

def/tdm_weapon_base.def

def/tdm_weapon_blackjack.def

def/tdm_weapon_broadhead.def

def/tdm_weapon_firearrow.def

def/tdm_weapon_gasarrow.def

def/tdm_weapon_mossarrow.def

def/tdm_weapon_noisemaker.def

def/tdm_weapon_ropearrow.def

def/tdm_weapon_shortsword.def

def/tdm_weapon_unarmed.def

def/tdm_weapon_vinearrow.def

def/tdm_weapon_waterarrow.def

def/triggers.def

 

31 def files fully documented

currently at 23%

[Flanders]

To know what the spawnargs on entities are for mappers need a description that is shown in dark radiant when adding that spawnarg. The problem is that for many entities these descriptions are not added yet, hence this thread. We need volunteers to go through the def files and give a description where they are missing. Above are the def files listed that need to be done.

If you are willing to help post here which def file you want to go through and report here when it's done. I'll scratch the finished ones so we know which ones are done.

 

To add a description just add "editor_var spawnargname" "explanation" to the def file.

example: "editor_var inherit" "Entitity inherits all properties from this parent entity"

These can be used for the different types of spawnargs:

* editor_bool - yes/no boolean values

* editor_gui - GUI definitions

* editor_color - Color values

* editor_vector - angles or vectors

* editor_float - floating point number

* editor_snd - sound shader name

 

etc. Possible values include: var, bool, int, float, model, string, gui, color, and material.

 

If the spawnarg is inherited add the description to the parent entity so that any other entity that inherit the same spawnarg will inherit the description. If the spawnarg is not inherited but can be found on many other entities add the description to a base entity they share (usually atdm:entity_base in tdm_base.def).

If you don't know what a spawnarg is for you can look in the script files or just ask.

 

Tels made a script that converts the info in the def files in an easy to use database. You'll need a program like activeperl or strawberryperl to run devel/inspec.pl that generates devel/doc/js/entities.js. The data in entities.js can be shown by opening devel/doc/index.html

 

for more info read this post:

http://forums.thedarkmod.com/index.php?s=&am...st&p=174474

or more general, the topic where this post is in:

http://forums.thedarkmod.com/index.php?showtopic=7360

the online documentation is here (updated frequently):

http://bloodgate.com/mirrors/tdm/pub/doc/index.html#overview

Edited January 22, 2009 by Flanders
added editor_sound spawnarg

[Flanders]

I'll start with triggers.def (I like to work from last to first). Therefore I need to make changes to triggers.def and to tdm_base.

[Flanders]

Done that one now, easy one .

[Flanders]

The weapon defs are too difficult for me, I don't understand half of it, someone more knowledgeable on this should do this. I'll do tdm_target.def now, that requires only some descriptions in the base entity I think.

[Flanders]

Should the editor_setKeyValue_thingies have a description? I guess not. In that case tdm_target.def is done

5% now, will do more tomorrow.

[Tels]

Please note that the correct type of the variable can also be coded in:

 

* editor_bool - yes/no boolean values

* editor_gui - GUI definitions

* editor_color - Color values

* editor_vector - angles or vectors seems actual not possible

 

etc. Possible values include: var, bool, int, float, model, string, gui, color, ,material and snd.

 

Interestingly enough, we have "editor_material" and "editor_mat". Greebo, does DR support both or is one a misspelling?

[Flanders]

Right, I also forgot to mention that the online documentation is found here and that the script files can be used to find out what a spawnarg does.

I'll update the second post.

[greebo]

You can leave editor_vector in there, it doesn't do any harm and editor support can be added later on.

 

editor_material is the one which is supported by DarkRadiant, it is used to automatically apply a certain texture to child brushes when creating triggers and such.

[SneaksieDave]

Chicken or egg question: If the field isn't there at all, how would we know what to add? For example,

 

triggers.def, entity: trigger_multiple

Consider the field:

"editor_var call" "script function to call when triggered."

 

If it originally appeared as,

"editor_var call" [no description here at all]

 

with no description, then it's straightforward; you just add a description and then it's fixed. Is the above even possible or would it cause a definition error? I've just found out that DR doesn't like it...

 

However if the whole property wasn't there at all, how would we know to add it? Even if there is an answer (e.g. check the script), that is a monumental task (just like it would be for mappers to blindly guess at properties), so I'm guessing (hoping) there's a better way that I'm just unaware of?

[Flanders]

The spawnarg editor_rotatable does not do what I suspected it does, if set to 0 on an entity it can still be rotated in DR. Perhaps it is no longer used in the code?

[Flanders]

Chicken or egg question: If the field isn't there at all, how would we know what to add?

Eggs were first if you like to know. Do you mean when you can't see the spawnarg in the def file cause it's inherited? Then use the documentation to see what spawnargs are inherited and add the editor description to the parent entity.

Sorry if I misunderstood you.

[Tels]

Chicken or egg question: If the field isn't there at all, how would we know what to add? For example,

 

triggers.def, entity: trigger_multiple

Consider the field:

"editor_var call" "script function to call when triggered."

 

If it originally appeared as,

"editor_var call" [no description here at all]

 

with no description, then it's straightforward; you just add a description and then it's fixed. Is the above even possible or would it cause a definition error? I've just found out that DR doesn't like it...

 

However if the whole property wasn't there at all, how would we know to add it? Even if there is an answer (e.g. check the script), that is a monumental task (just like it would be for mappers to blindly guess at properties), so I'm guessing (hoping) there's a better way that I'm just unaware of?

 

If the C++ or the script code f.i. uses a new spawnarg named "fritzelbobble", then no, you wouldn't know about it unless it is either documented in the def files, or used or both.

 

However, for now I would focus on documenting the currently used spawnargs as these either do something, or are no longer useful and need to be removed.

 

We probably never get it to 100% documented, but getting further than 60% would be a start

[Flanders]

If I just knew what editor_rotatable and sprs_bounce was for I could scratch a lot of def files from the to do list.

[greebo]

editor_rotatable applies only to DoomEdit (DR doesn't support it), but I don't know what it actually does.

 

All spawnargs with "sprS" are soundprop-related ones. They refer to other entityDefs containing soundprop definitions. This basically defines how a certain sound should "feel" like for AI, how far it propagates etc.

[Springheel]

5% is probably a considerable underestimate, as many of those def files reuse the same properties.

[Flanders]

5% is probably a considerable underestimate, as many of those def files reuse the same properties.

There are only a few def files with all properties of all entities in it documented, that's the 6%. If people help and document properties, especially those that are very common among many def files, that percentage can rise quickly.

[SneaksieDave]

@Flanders, Tels:

Okay this is getting a bit jargon-y and confusing for me, so to put it in layman's "what I see" terms...

 

If I look at the definition of frobable_base, I see the properties:

 

"inherit"

"editor_usage"

"editor_displayFolder"

"editor_bool frobable"

"editor_int frob_distance"

"editor_var frob_peer"

"editor_bool immune_to_target_setfrobable"

"editor_var frob_action_script"

"editor_string equip_action_script"

"editor_bool equippable"

"editor_bool grabable"

"frobable"

"frob_action_script"

"grabable"

"spawnclass"

"solid"

"noclipmodel"

 

Though it is assumed some aren't displayed as they are "internal" use only (e.g. editor_usage). I don't know how it determines which to show and which not, as I was asking elsewhere, but whatever. Now further, since it inherits entity_base,

 

"editor_var inherit"

"editor_color editor_color"

"editor_var editor_displayfolder"

"editor_var editor_maxs"

"editor_var editor_mins"

"editor_int team"

"editor_float absence_noticeability"

"editor_var absence_location"

"editor_float absence_bounds_tolerance"

"editor_float absence_alert"

"editor_string set"

"editor_var editor_material"

"editor_bool editor_showangle"

"editor_bool nodraw"

"editor_vector origin"

 

Ignoring a duplicate or two, that's a lot of stuff. Here's what's displayed on the docs site:

 

editor_displayfolder

frob_action_script

frobable

grabable

inherit

noclipmodel

solid

spawnclass

 

Huge difference. Where are the rest? Again I understand some won't be shown as they are internal, but where is for example, the documented absence stuff? Where is set? Frob_peer? If they aren't shown to the user, the user won't know they can be used. Opportunity lost. (The whole point of my campaign here.)

 

So, since it's established that the site isn't (currently) showing all information, the original question is: how do we know to document the properties if they aren't shown to us? It's like finding something which isn't there.

[Tels]

@Flanders, Tels:

Huge difference. Where are the rest?

 

Let me repeat it again. The online doc shows set spawnargs. It does NOT show sparnargs that are documented, but not actually set on the entity.

 

So if you have:

 

entityDef foo {
"editor_var blah" "FOO"
"editor_var BUZ" "ABC"

"BUZ" "123"
}

 

then the doc will show "BUZ" but NOT "blah" because blah is not used/defined on that entity, merely documented. I am working on that.

 

Or in other words, merely documenting a spawnarg makes it neither valid, nor does it set a default value. It just enables the user to add that spawnarg inside DR (wrongly or not).

 

Hope that clears that finally up

[SneaksieDave]

The online doc shows set spawnargs. It does NOT show sparnargs that are documented, but not actually set on the entity.

Tels: I understand that. But my entire point behind the year+ adventure in this topic has been: that is of limited benefit to the user. The online docs are awesome IMO, but what I'm trying to say, the user should see all of the properties that are available to them, or they won't know that they are available. Perhaps it is more needed in DR (where it apparently does work that way thankfully), but I think it would even be beneficial on the docs site (perhaps shown in some other way, italicized or grey or something). That way they see the props right in front of them, instead of having to:

1. understand inheritance like a programmer (which many won't),

2. go hunting for unseen properties (which is confusing, error prone and time consuming),

3. take random stabs in the dark (which is time consuming and frustrating)

 

If you meant above that you are "working on that", that's awesome. Seems we were speaking of the same thing but saying it from different ends. You are saying "it doesn't work that way," and I'm saying, "yeah I know; can it?"

[Tels]

Tels: I understand that. But my entire point behind the year+ adventure in this topic has been: that is of limited benefit to the user. The online docs are awesome IMO, but what I'm trying to say, the user should see all of the properties that are available to them, or they won't know that they are available. Perhaps it is more needed in DR (where it apparently does work that way thankfully), but I think it would even be beneficial on the docs site (perhaps shown in some other way, italicized or grey or something). That way they see the props right in front of them, instead of having to:

1. understand inheritance like a programmer (which many won't),

2. go hunting for unseen properties (which is confusing, error prone and time consuming),

3. take random stabs in the dark (which is time consuming and frustrating)

 

If you meant above that you are "working on that", that's awesome. Seems we were speaking of the same thing but saying it from different ends. You are saying "it doesn't work that way," and I'm saying, "yeah I know; can it?"

 

Well, yeah, first: I can easily add whatever you guys want. Second: I just spent a lot of time on it, but with very little feedback except "it works like a charm". So I have no real idea what to add. Plus, I have only limited time, and limited energy. Sorry

 

So, yes I will add the documented spawnargs on the entity view, but I need just to find some time to do it, ok?

 

The entire "online doc" thingy is still experimental and can be improved, the problem is just that neither me, nor you or anybody else has a good idea what we actually need, so we all make stuff up as we go along

[Flanders]

All spawnargs with "sprS" are soundprop-related ones. They refer to other entityDefs containing soundprop definitions. This basically defines how a certain sound should "feel" like for AI, how far it propagates etc.

If it has a value of bounce_default:-5, does this mean it has the volume of bounce_default minus 5? Or does this apply to some other value inside the soundprop def?

[greebo]

If it has a value of bounce_default:-5, does this mean it has the volume of bounce_default minus 5? Or does this apply to some other value inside the soundprop def?

It means both. The value after the colon : is an optional volume modifier (-5 db), which gets applied to the "volume" value in the soundprop def (see sprGS_bounce_default).

[Flanders]

Working on moveables now.

[Flanders]

More than 10 percent now. I realized now that there are also a lot of entities without editor_usage, these should also be added for all of them.

 

Spawnargs found this time for which I don't know what they're for: nopulse (bool) and networksynch (bool, something with the sound channels perhaps).