Skip to content

Updating @example sections for several EntityTag Mechanism's and Tags. #2813

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
Skullfurious wants to merge 8 commits into
base: dev
Choose a base branch
from
+19 −1
Open

Updating @example sections for several EntityTag Mechanism's and Tags. #2813

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cb12e5d
Add @example to EntityTag.velocity
Skullfurious Feb 2, 2026
cf1832d
Add @example to EntityTag.world
Skullfurious Feb 2, 2026
45e1bea
Add @example to EntityTag.glowing
Skullfurious Feb 2, 2026
d57e85b
Add @example to several tags and mechanisms.
Skullfurious Feb 2, 2026
56037f5
Adjust examples based on feedback.
Skullfurious Feb 3, 2026
d980299
Removed imports
Skullfurious Feb 3, 2026
3c4a3d4
Requested Changes submitted
Skullfurious Feb 5, 2026
246d113
Typo
Skullfurious Feb 5, 2026
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
23 changes: 22 additions & 1 deletion plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1257,6 +1257,8 @@ public static void register() {
// @returns ElementTag
// @deprecated Use 'EntityTag.type' on MC 1.20+.
// @description
// Returns the entities type.
// Note: For NPC's this will return the value "Player".
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

This is deprecated, is there any reason you're adding back the meta?

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

Mainly because I ran into an issue with EntityTag.type also throwing a deprecated error on NPC's and figured I would just document the behaviour since EntityTag.entity_type behaves differently than EntityTag.type (which says NPC).

I will remove it in the next commit!

// Deprecated in favor of <@link tag EntityTag.type> on MC 1.20+, which returns entity type names as specified by Mojang (scripts using this may need an update when switching).
// -->
tagProcessor.registerTag(ElementTag.class, "entity_type", (attribute, object) -> {
Expand Down Expand Up @@ -1563,6 +1565,9 @@ else if (object.getLivingEntity() instanceof Steerable) {
// @group location
// @description
// Returns the location of the entity's eyes.
// @example
// # Shoots a snowball from the direct center of the players screen.
// - shoot snowball origin:<player.eye_location> destination:<player.location.facing> speed:1
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

Make sure you test examples in-game to verify they work as expected, I.e. in this case I believe this will error because LocationTag.facing requires a parameter & returns a boolean.
Although you can just remove that entire destination arg here I believe? Keep the example as simple as possible.

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

I see what you mean, I had debug off. I'll avoid doing that in the future. Thanks for catching that.

// -->
registerSpawnedOnlyTag(LocationTag.class, "eye_location", (attribute, object) -> {
return new LocationTag(object.getEyeLocation());
Expand Down Expand Up @@ -1676,7 +1681,17 @@ else if (object.getLivingEntity() instanceof Steerable) {
// @mechanism EntityTag.velocity
// @description
// Returns the movement velocity of the entity.
// There is a constant negative velocity of '-0.08' when standing on a block.
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

I don't know if I'd put that in the meta, that's more of an implementation detail Mojang could change whenever they feel like

// Note: Does not accurately calculate player clientside movement velocity.
// @example
// # Checks if the player is jumping:
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

Maybe label this as "going upwards"/"moving upwards" or something like that, this might be a bit misleading as it's not an actual jumping check.

// - if <player.velocity.y.is_more_than[0]>:
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

Image

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

Ah, just seen this after my previous comment. I was going down the list replying.

I'll fix that now but I was curious if there was a reason why it's a bad idea?

Copy link
Copy Markdown
Member

@mcmonkey4eva mcmonkey4eva Feb 5, 2026

Choose a reason for hiding this comment

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

The tag only exists to allow operators outside of the if command. The if command already can do - if <player.velocity.y> > 0: as the syntax

Copy link
Copy Markdown
Member

@mcmonkey4eva mcmonkey4eva Feb 5, 2026

Choose a reason for hiding this comment

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

This example is also bad regardless, // Note: Does not accurately calculate player clientside movement velocity. player should not be used as an example on the velocity tag

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

It does seem to track the vertical movement correctly just not the X and Y after my testing. Do you think I should use context.entity instead of player?

// - narrate "The player is jumping!"
// - else:
// - narrate "The player is not jumping!"
// @example
// # Makes the player jump:
// - adjust <player> velocity:<location[0,1,0]>
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

Why is this an example on the velocity tag? If anything it should be on the mechanism - also that constructor shouldn't be required.

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

There were a few other tags that had examples using the adjust command as well. I believe in this case the generated example was not very usable since it was

- teleport <player> <player.velocity>

If you have a better example I could definitely change it. I was under the impression just using narrate was not a good example script as well.

Would something like this be better?

- if <player.velocity.y.is_more_than[0]>:
    - narrate "Player is ascending!"

Copy link
Copy Markdown
Author

@Skullfurious Skullfurious Feb 5, 2026

Choose a reason for hiding this comment

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

I didn't realize you could just pass in the raw values of value:0,1,0 haha I thought you had to pass a location tag explicitly.

// -->
registerSpawnedOnlyTag(LocationTag.class, "velocity", (attribute, object) -> {
return new LocationTag(object.getBukkitEntity().getVelocity().toLocation(object.getBukkitEntity().getWorld()));
Expand All @@ -1688,6 +1703,9 @@ else if (object.getLivingEntity() instanceof Steerable) {
// @group location
// @description
// Returns the world the entity is in. Works with offline players.
// @example
// # Narrates the world name that the linked player is in.
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

...the name of the world that...

// - narrate <player.world.name>
// -->
registerSpawnedOnlyTag(WorldTag.class, "world", (attribute, object) -> {
return new WorldTag(object.getBukkitEntity().getWorld());
Expand Down Expand Up @@ -2339,7 +2357,7 @@ else if (object.getBukkitEntity() instanceof Hanging hanging) {
// @mechanism EntityTag.glowing
// @group attributes
// @description
// Returns whether this entity is glowing.
// Returns whether this entity is glowing (Has an outline around them).
Copy link
Copy Markdown
Member

@tal5 tal5 Feb 4, 2026

Choose a reason for hiding this comment

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

Lowercase H here I believe

// -->
registerSpawnedOnlyTag(ElementTag.class, "glowing", (attribute, object) -> {
return new ElementTag(object.getBukkitEntity().isGlowing());
Expand Down Expand Up @@ -3892,6 +3910,9 @@ public void adjust(Mechanism mechanism) {
// Sets the entity's movement velocity vector.
// @tags
// <EntityTag.velocity>
// @example
// # Launches the player upwards by adjusting their velocity.
// - adjust <player> velocity:<location[0,1,0]>
// -->
if (mechanism.matches("velocity") && mechanism.requireObject(LocationTag.class)) {
setVelocity(mechanism.valueAsType(LocationTag.class).toVector());
Expand Down