Skip to content

corrected and clarified some stuff related to action functions #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

corrected and clarified some stuff related to action functions #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions glossary/Concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ These can be defined either in the `states` block header as-is, or in `Actor`'s
| `SUF_OVERLAY` | `overlay` |
| `SUF_WEAPON` | `weapon` |

The effect of this is described in the Methods section.

## Object Scoping

Most objects are subject to object scoping, which restricts the way data can be
Expand Down
33 changes: 20 additions & 13 deletions language/Methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,8 +83,8 @@ DoSomething(7, 8, 9, 10);

| Flag | Description |
| ---- | ----------- |
| `action ( Scope )` | Same as `action`, but has a specified action scope. See "Action Scoping" for more information. |
| `action` | Method has implicit `invoker` and `stateinfo` parameters. See below for more info. |
| `action ( Scope $[ , Scope]$... )` | Same as `action`, but has specified action scopes. See "Action Scoping" for more information. |
| `action` | Method may have implicit `invoker` and `stateinfo` parameters. See below for more info. |
| `clearscope` | Method has Data scope. |
| `deprecated ( "ver" $[ , "reason" ]$ )` | If accessed, a script warning will occur on load if the archive version is greater than `ver`, with the reason `reason` specified in the message. |
| `final` | Virtual method cannot be further overridden from derived classes. |
Expand All @@ -105,16 +105,23 @@ DoSomething(7, 8, 9, 10);
ZScript includes an extra method type for descendents of `Actor` called
*actions*, which are intended to be run from actor states and give extra
information to the function. Action functions change the meaning of the `self`
parameter and pass in `invoker` and `stateinfo` parameters as well. `stateinfo`
refers to the `State` which this action was called from. Here is a chart for
the meanings of the `self` and `invoker` variables under each scope:

| Scope | `self` meaning | `invoker` meaning |
| ----- | -------------- | ----------------- |
| None | The actor this function operates on, ambiguous in some contexts | State owner |
| `actor` | The actor | The actor |
| `item` | Item owner | Item itself |
| `overlay` | Weapon owner | Weapon itself |
| `weapon` | Weapon owner | Weapon itself |
parameter and may pass in `invoker` and `stateinfo` parameters as well. `stateinfo`
refers to the `State` which this action was called from.

Action scopes are a flag field and as such an action function can have multiple scopes.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a little too specific, preferably this would be written as user-facing documentation rather than from an implementation perspective. I would suggest the phrasing "Action functions may have one scope or multiple scopes."

The only scopes that actually set the internal action function flag are `item`, `overlay` and `weapon`,
so action functions without one of these do not act much like action functions, and they do not get an
`invoker` or `stateinfo` pointer.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Preferably this would also be rephrased as something like "Actor scope and un-scoped action functions do not have invoker or stateinfo parameters and as such are not often useful." Followed by an explanation of what these two do and in what circumstances they may be useful.


Here is a chart for the meanings of the `self` and `invoker` variables under each scope.
Scopes lower down on the chart "override" scopes above them, so to speak:

| Scope | `self` meaning | `invoker` meaning |
| ----- | -------------- | ----------------- |
| None | The actor this function operates on, ambiguous in some contexts | N/A |
| `actor` | The actor | N/A |
| `item` | Context-dependent. The item itself when it exists in-world, but the owner when used as part of a CustomInventory state chain | Item itself |
| `overlay` | Context-dependent. The actor itself when it exists in-world, but the owner of the PSprite when it is being used as one | Context-dependent. The actor itself when it exists in-world, but the PSprite's `caller` field when it is being used as one. In most cases this field should be set to be the actor defining the action function, but it can be changed by user code so this is not technically guaranteed |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PSprite is a technical term, which while correct, is not very intuitive. Preferably "the weapon" would be used here because it is an equivalent term in abstract.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PSprite is a technical term, which while correct, is not very intuitive. Preferably "the weapon" would be used here because it is an equivalent term in abstract.

That's not actually correct. PSprites don't have to be weapons, and don't have to be contained in them.

| `weapon` | Same as `overlay`, but `self` is allowed to be any subclass of `Actor` rather than just a subclass of the defining class | Same as `overlay` |

<!-- EOF -->