ZDoom Wiki Thread

[Blue Shadow]

There is a typo in "This article lists no examples" note:


While I'm here, I'd like to thank Phantombeta, Blue Shadow, Bauul, Marrub, and other people who keep the wiki updated. It's very important work.

Fixed. And you're welcome.

[Jekyll Grim Payne]

Hello there, folks. Ever since I started learning ZScript I've been noticing certain inconsistencies on the wiki, such as argument names not matching their actual names (A_CustomRailgun and A_RailAttack have been the offenders, I've fixed them so far).

My next idea is a bit more radical: change the formatting of the functions. Change it from this:

Code: Select all

A_RailAttack (int damage [, int spawnofs_xy [, bool useammo [, color color1 [, color color2 [, int flags [, int maxdiff [, Class<Actor> pufftype [, double spread_xy [, double spread_z [, double range [, int duration [, double sparsity [, double driftspeed [, Class<Actor> spawnclass [, double spawnofs_z [, int spiraloffset [, int limit]]]]]]]]]]]]]]]]])

..which has a bunch of basically useless brackets and lacks default values

To this:

Code: Select all

A_RailAttack(int damage, int spawnofs_xy = 0, bool useammo = true, color color1 = 0, color color2 = 0, int flags = 0, double maxdiff = 0, class<Actor> pufftype = "BulletPuff", double spread_xy = 0, double spread_z = 0, double range = 0, int duration = 0, double sparsity = 1.0, double driftspeed = 1.0, class<Actor> spawnclass = "none", double spawnofs_z = 0, int spiraloffset = 270, int limit = 0)

...which is how it looks in gzdoom.pk3, so imo, no reason for it to look any different on the wiki

It obviously can't be done to all functions overnight, but I think it's a good idea and I'm ready to contribute where I can.


P.S. In addition to that I think we should be adding ZScript examples next to DECORATE examples whenever we can. I've only done it to a few pages so far but I plan to continue.

[NeuralStunner]

The "useless brackets" are syntax notation for "this is optional", but the way they're stacked is because they're not optional if argmuents after are used. It's a messy situation that can only really be solved by support for named argument calls. (Not sure if ZScript does/will support this. In either case, if not, this is going to need a different approach than just copy-pasting from the PK3.)

Defaults are provided in the argument explanations below. This is especially important in cases where the default is 0, but that value has a special meaning.

[InsanityBringer]

It's a messy situation that can only really be solved by support for named argument calls. (Not sure if ZScript does/will support this. In either case, if not, this is going to need a different approach than just copy-pasting from the PK3.)

ZScript does support this feature, but with some limitations (they have to be in the same order they're defined in the function definition)

to be quite honest, it has made calling the function in question much, much cleaner. This feature is a good reason to go around and double check that args are named properly on the wiki.

[Jekyll Grim Payne]

The "useless brackets" are syntax notation for "this is optional", but the way they're stacked is because they're not optional if argmuents after are used.

I know why they are there. It still doesn't seem useful at all to me. The majority of arguments are optional, so I don't see the point of stating that explicitly, and if we provided default values right there, that would imply that you can omit arguments, so that default values are used instead. Also, a complete newbie who opens the wiki for the firt time might not be even familiar with that notation (like I wasn't 12 years ago), and it just confuses them more. So, I don't see the point of those brackets. I do see how they make the thing harder to read. And as for providing values right next to the arguments instead of only providing those below — this would be an obviously huge increase in readability: we'd see all values in one place instead of having to read through descriptions.

[NeuralStunner]

Also, a complete newbie who opens the wiki for the firt time might not be even familiar with that notation (like I wasn't 12 years ago), and it just confuses them more.

That's how professional language references do it.

Newbies wouldn't know that "this = that" makes arguments optional, either. It'd still look verbose and confusing, just in a different way. Ultimately, non-programmers probably shouldn't be trying to learn programming from the language documentation.

Mind you, I'm not saying that the brackets aren't messy-looking and annoying on long functions... Just that they're not useless. The main issue is making sure the documentation still works for Decorate as well - There are years of live code out there. I think a template - Linking to a page on syntax notation, with a description of how named/optional arguments work, and Decorate limitations - would be the the best way to make the changes work. Reformatting won't mean a thing if it's still not clear how it actually works.

[Void Weaver]

Somebody fix a wrong description of A_CheckBlock, please:

Performs a check and jumps to block state based upon if an actor or a line is blocking the caller.

There should be smth like:

Performs a check and jumps to block state based upon if an actor or a line is blocking the caller's checking point with specified offset.

For that reason is a broken example there, it should be like this one instead:

Actor NevrousZombie4ZDWiki replaces Zombieman //Properly work restrict using inheritance here and requires the full definition actually.
{
Health 20
Radius 20
Height 56
Speed 8
PainChance 200
Monster
+FLOORCLIP
SeeSound "grunt/sight"
AttackSound "grunt/attack"
PainSound "grunt/pain"
DeathSound "grunt/death"
ActiveSound "grunt/active"
Obituary "$OB_ZOMBIE" // "%o was killed by a zombieman."
DropItem "Clip"
States
{
Spawn:
POSS AB 10 A_Look
Loop
See:
POSS AA 4 Fast A_Chase
POSS A 0 A_CheckBlock("Nevrous",CBF_SETTARGET,AAPTR_DEFAULT,Radius+1)
POSS BB 4 Fast A_Chase
POSS B 0 A_CheckBlock("Nevrous",CBF_SETTARGET,AAPTR_DEFAULT,Radius+1)
POSS CC 4 Fast A_Chase
POSS C 0 A_CheckBlock("Nevrous",CBF_SETTARGET,AAPTR_DEFAULT,Radius+1)
POSS DD 4 Fast A_Chase
POSS D 0 A_CheckBlock("Nevrous",CBF_SETTARGET,AAPTR_DEFAULT,Radius+1)
Loop
Pain:
POSS G 3
POSS G 3 A_Pain
Goto Nevrous
Nevrous:
POSS AABBCCDD 2 Fast A_Wander
POSS A 0 A_Jump( 63, "See" )
Loop
Death:
POSS H 5
POSS I 5 A_Scream
POSS J 5 A_NoBlocking
POSS K 5
POSS L -1
Stop
}
}

================
To all zwiki members who can edit and add an new articles:
Write-in in articles GZDoom version in which that feature was introduced and keep it from deleting please. It's very helpful info for backward compatibility modding!
I have notice that those notes was implemented for a some time in new articles after 3.6 but then was deleted. So sad. Q_Q

[Blue Shadow]

Write-in in articles GZDoom version in which that feature was introduced and keep it from deleting please. It's very helpful info for backward compatibility modding!

If we tagged every feature, it'd create a lot of "noise" when reading a page, I'd feel. But that's just me...

I have notice that those notes was implemented for a some time in new articles after 3.6 but then was deleted. So sad. Q_Q

That's because the feature is no longer considered new.

[Void Weaver]

Write-in in articles GZDoom version in which that feature was introduced and keep it from deleting please. It's very helpful info for backward compatibility modding!

If we tagged every feature, it'd create a lot of "noise" when reading a page, I'd feel. But that's just me...

Seems that you are very demanding person. Because I just understand how exactly a such tiny notification can create a some visual "noise". o_0

I have notice that those notes was implemented for a some time in new articles after 3.6 but then was deleted. So sad. Q_Q

That's because the feature is no longer considered new.

What if change sense of tag from "new" to "first" (for ex.)? That would be mean that pointed index (version) are "first" where this feature was implemented as regular release.
----------
Btw, A_CheckBlock article still have a wrong description and wrong example for current function mechanics. Fix it please anybody.

EDIT:
Also A_Countdown description is wrong too for now, it says:

This can only be used on projectiles. It counts ReactionTime down until it reaches 0 and then explodes the projectile.

It's not true. Non-specified (non-missile\monster) actors can die also after RTime were counted down.

[Blue Shadow]

Seems that you are very demanding person. Because I just understand how exactly a such tiny notification can create a some visual "noise". o_0

I wasn't talking about a tag per page, but a tag per feature. Some features get extended overtime, like a function which could get additional parameters or flags. Wouldn't these need tagging as well? The "new" and "git" tags are temporary, and are removed eventually, so they wouldn't create as much noise.

Btw, A_CheckBlock article still have a wrong description and wrong example for current function mechanics. Fix it please anybody.

I don't know anything about that function nor do I have any experience with using it. So I'd like to get some sort of verification from someone on the changes you're suggesting to be made first. No offense.

[Void Weaver]

Seems that you are very demanding person. Because I just understand how exactly a such tiny notification can create a some visual "noise". o_0

I wasn't talking about a tag per page, but a tag per feature. Some features get extended overtime, like a function which could get additional parameters or flags. Wouldn't these need tagging as well? The "new" and "git" tags are temporary, and are removed eventually, so they wouldn't create as much noise.

Well, actually I assume tag per page indeed, - that gives a versionstamp when a basic feature (function\keyword\a some tool\a new method\etc.) was introdused first time. Ofc are lots of things were updated, buffed and revamped during time and version-tagging for each new addition would be really a bit eyes-breaking. Therefore I mean versionstamp only for first release.

Btw, A_CheckBlock article still have a wrong description and wrong example for current function mechanics. Fix it please anybody.

I don't know anything about that function nor do I have any experience with using it. So I'd like to get some sort of verification from someone on the changes you're suggesting to be made first. No offense.

I agree with you that "measure twice cut once" is safer treatment but there is easy to make sure that current description is wrong even without having any experience with this function, since the current example doesn't work anymore (but it was worked earlier), but mine is works.
Also presence of "x/y/zofs: Offsets the position to check by this much." already contradicts with current statement that block check performs by whole caller itself. Even editings history shows that _CBlock behaviour were changes from GZDoom 2.4.0 release.
------
What about A_Countdown, just summon this thing and you see as it vanishes after 5 sec, though it isn't missile at all:

Code: Select all

Actor FakeIBall
{
+NOGRAVITY
+NOINTERACTION
ReactionTime 175
States
{
Spawn:
BAL1 AB 1 A_Countdown
Loop
Death:
TNT1 A 0
Stop
}
}

Actually it even can kills monsters too, despite that they will not loose any health:

Code: Select all

Actor CDownZ : ZombieMan replaces ZombieMan
{
ReactionTime 15
+NOINTERACTION
States
{
See:
POSS AABBCCDD 4 A_Chase
TNT1 A 0 A_Countdown
Loop
}
}

[Rachael]

Void Weaver - we're not interested in "backward compatibility" modding.

Use the newest version of GZDoom. Period.

The "introduced in version X" notices are going to stay gone.

There are a multitude of reasons why you should not use old versions of GZDoom and let's not even get into the security implications of it.

The only exception I will ever make for this is Zandronum - but in general, everything that isn't ZScript works in Zandronum anyway, so there's very little worry there.

[Blue Shadow]

Therefore I mean versionstamp only for first release.

If your interest is when a feature was first introduced, the only thing a can suggest at this point is to check the page editing history of said feature. That's all I have.

What about A_Countdown, just summon this thing and you see as it vanishes after 5 sec, though it isn't missile at all

Okay, from looking at the source code, the function doesn't perform a check on the caller to see if it's a missile or not. But, it assumes it to be a missile. So it's up to the modder to use the function properly, I guess...

[Void Weaver]

@Blue Shadow
Oookay... I understand your point. So it's better way to look into article history and then seek and compare port version release date and compare to article creating date. Instead of just leaving a small note on a page. Got it.
@Rachael
And no, ma'am I personally use port latest (+\- one release) version for modding, despite that I've always tries to write code maximal compatible with earlier versions as it possible.

Well, then subject can be considered closed, I guess.
--------

Okay, from looking at the source code, the function doesn't perform a check on the caller to see if it's a missile or not. But, it assumes it to be a missile. So it's up to the modder to use the function properly, I guess...

Anyway it have no influence on the fact that current description haven't match to actual function mechanics.
Therefore there is need to do one of either: restrict working area of A_Countdown by missiles only, OR edit description in appropriate to the current mechanics. Moreover, there is nothing difficult to place note that function work are supposed to be affect only missiles initially but for some reason now it works with non-missile actors too.

[Blue Shadow]

I'm sorry that I have to do this (again), but I'll wait and see if Graf has anything to say on the matter, since looking at the edit history of the page, it was he who added the documentation for the function, which has remained pretty much the same until this day.