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

@Skullfurious Skullfurious commented Feb 2, 2026

Copy link

Copy Markdown

This PR adds some missing @example sections to various Mechanisms and Tags.

Tags:

EntityTag.velocity
EntityTag.world
EntityTag.glowing
EntityTag.entity_type
EntityTag.type
EntityTag.name
EntityTag.eye_location

Mechanisms:

EntityTag Mechanism: velocity

Skullfurious added 4 commits

February 2, 2026 02:16


 Add @example to EntityTag.velocity

cb12e5d


 Add @example to EntityTag.world

cf1832d


 Add @example to EntityTag.glowing

45e1bea


 Add @example to several tags and mechanisms.

d57e85b

@CLAassistant

CLAassistant commented Feb 2, 2026 •

edited

Loading

Copy link

Copy Markdown

CLA assistant check
All committers have signed the CLA.

mcmonkey4eva reviewed

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @returns ElementTag

// @deprecated Use 'EntityTag.type' on MC 1.20+.

// @description

// Returns the entities type. NOTE: For NPC's it will say "PLAYER".

@mcmonkey4eva mcmonkey4eva Feb 2, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

This is not well written

mcmonkey4eva reviewed

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

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

// @example

// # Describes the type of entity at the players cursor in the world.

// # For use in-game: /ex narrate <player.target.entity_type>

@mcmonkey4eva mcmonkey4eva Feb 2, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

we do not need every example doc to tell you about the /ex command

mcmonkey4eva reviewed

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// Returns the type of the entity.

// @example

// # Checks if the entity that a player is looking at is also a player.

// # - if <player.target.type> == Player:

@mcmonkey4eva mcmonkey4eva Feb 2, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

this is a bad script, for multiple reasons. The if/else is silly, the target tag is used without a fallback

mcmonkey4eva reviewed

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @example

// # Checks if the player's name is "mcmonkey".

// # For use in game: /ex narrate <player.name.matches[mcmonkey]>

// - if <player.name> == mcmonkey:

@mcmonkey4eva mcmonkey4eva Feb 2, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

This is actively violating one of the basic points in the Denizen beginner's guide

mcmonkey4eva reviewed

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @example

// # Narrates the linked player's eye location.

// # /ex narrate <player.eye_location>

// - narrate <player.eye_location>

@mcmonkey4eva mcmonkey4eva Feb 2, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

just narrating tags is not a very good example usage


 Adjust examples based on feedback.

56037f5

Entity.world and velocity had examples that weren't very useable in their generated form.

Skullfurious commented Feb 3, 2026

Copy link

Copy Markdown

Author

Thanks for the feedback, I opened a thread on the discord.


 Removed imports

d980299

tal5

tal5 requested changes

Feb 4, 2026

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @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.

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

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// There is a constant negative velocity of '-0.08' when standing on a block.

// Note: Does not accurately calculate player clientside movement velocity.

// @example

// # Checks if the player is jumping:

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.

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// - narrate "The player is not jumping!"

// @example

// # Makes the player jump:

// - adjust <player> velocity:<location[0,1,0]>

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.

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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.

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// 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

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.

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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.

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @description

// Returns the world the entity is in. Works with offline players.

// @example

// # Narrates the world name that the linked player is in.

@tal5 tal5 Feb 4, 2026

Copy link

Copy Markdown

Member

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

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// @group attributes

// @description

// Returns whether this entity is glowing.

// Returns whether this entity is glowing (Has an outline around them).

@tal5 tal5 Feb 4, 2026

Copy link

Copy Markdown

Member

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

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

// Note: Does not accurately calculate player clientside movement velocity.

// @example

// # Checks if the player is jumping:

// - if <player.velocity.y.is_more_than[0]>:

@tal5 tal5 Feb 4, 2026

Copy link

Copy Markdown

Member

Choose a reason for hiding this comment

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

Image

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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?

@mcmonkey4eva mcmonkey4eva Feb 5, 2026

Copy link

Copy Markdown

Member

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

@mcmonkey4eva mcmonkey4eva Feb 5, 2026

Copy link

Copy Markdown

Member

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

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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?

plugin/src/main/java/com/denizenscript/denizen/objects/EntityTag.java Outdated

Comment on lines +1260 to +1261

// Returns the entities type.

// Note: For NPC's this will return the value "Player".

@tal5 tal5 Feb 4, 2026

Copy link

Copy Markdown

Member

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?

@Skullfurious Skullfurious Feb 5, 2026

Copy link

Copy Markdown

Author

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!

Skullfurious added 2 commits

February 5, 2026 02:18


 Requested Changes submitted

3c4a3d4


 Typo

246d113