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

Skullfurious · 2026-02-02T08:21:56Z

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

CLAassistant · 2026-02-02T08:22:06Z

All committers have signed the CLA.

mcmonkey4eva · 2026-02-02T19:23:07Z

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

        // @returns ElementTag
        // @deprecated Use 'EntityTag.type' on MC 1.20+.
        // @description
+        // Returns the entities type. NOTE: For NPC's it will say "PLAYER".


This is not well written

mcmonkey4eva · 2026-02-02T19:23:27Z

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

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


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

mcmonkey4eva · 2026-02-02T19:24:09Z

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

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


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

mcmonkey4eva · 2026-02-02T19:24:31Z

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

+        // @example
+        // # Checks if the player's name is "mcmonkey".
+        // # For use in game: /ex narrate <player.name.matches[mcmonkey]>
+        // - if <player.name> == mcmonkey:


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

mcmonkey4eva · 2026-02-02T19:24:49Z

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

+        // @example
+        // # Narrates the linked player's eye location.
+        // # /ex narrate <player.eye_location>
+        // - narrate <player.eye_location>


just narrating tags is not a very good example usage

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

Skullfurious · 2026-02-03T04:34:33Z

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

tal5 · 2026-02-04T23:36:02Z

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

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


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

tal5 · 2026-02-04T23:37:20Z

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

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


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.

tal5 · 2026-02-04T23:40:57Z

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

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


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

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

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.

tal5 · 2026-02-04T23:45:41Z

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

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


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.

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

tal5 · 2026-02-04T23:47:06Z

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

        // @description
        // Returns the world the entity is in. Works with offline players.
+        // @example
+        // # Narrates the world name that the linked player is in.


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

tal5 · 2026-02-04T23:50:43Z

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

        // @group attributes
        // @description
-        // Returns whether this entity is glowing.
+        // Returns whether this entity is glowing (Has an outline around them).


Lowercase H here I believe

tal5 · 2026-02-04T23:51:06Z

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

        // Note: Does not accurately calculate player clientside movement velocity.
+        // @example
+        // # Checks if the player is jumping:
+        // - if <player.velocity.y.is_more_than[0]>:


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?

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

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

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?

tal5 · 2026-02-04T23:55:51Z

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

+        // Returns the entities type.
+        // Note: For NPC's this will return the value "Player".


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

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

mcmonkey4eva reviewed Feb 2, 2026

View reviewed changes

Adjust examples based on feedback.

56037f5

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

Removed imports

d980299

tal5 requested changes Feb 4, 2026

View reviewed changes

Skullfurious added 2 commits February 5, 2026 02:18

Requested Changes submitted

3c4a3d4

Typo

246d113

Skullfurious requested a review from tal5 February 6, 2026 05:46

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

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

Skullfurious commented Feb 2, 2026

Uh oh!

CLAassistant commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Skullfurious commented Feb 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Feb 2, 2026 •

edited

Loading