Extend @context for more than just entities

[NeunEinser]

The context of a function can be more than just the entity @s.

Currently, IMP only allows defining entity context.

I already adapted it in my projects and use @context like this:

#> 91:function_that_requires_a_dimension
# ...
# @context dimension The dummy dimension to use for placing temporary blocks

#> 91:function_that_requires_entity_and_pos
# ...
# @context
#   entity The entity to do funky stuff with
#   position Must be set to at @s

I suggest allowing @context for all of the following:

• dimension
• entity
• position
• rotation

Not setting one of these options implies that it may be set to anything. For position and rotation, set to root, if the context is required to be root (typically world spawn)

@handles #minecraft:tick and @handles #minecraft:load imply:

#> 91:function_that_requires_entity_and_pos
# ...
# @handles #minecraft:tick
# @context
#   dimension minecraft:overworld
#   entity none
#   position root
#   rotation root

[Arcensoth]

I think it would be useful to extend support for documenting execution context, but I'm undecided whether it should be purely through @context as opposed to annotations with a finer granularity. For example, using @in minecraft:overworld to denote the dimension, or @as Some marker entity the entity.

Something that I don't think I've documented but I've already been doing a lot lately is using @positioned some:arbitrary/name to denote that a precise execution position is expected. The some:arbitrary/name is a made-up identifier for a special position I generally list in my readme. I can #DEFINE it with DHP or find-all/find-and-replace with my editor to quickly locate all functions that use these particular coordinates.

Extending @context itself has the advantage that it encapsulates the concept of "execution concept" but the fine-grained annotations have the advantage that they're solely responsible for a particular thing.

[NeunEinser]

I don't know which of these I'd prefer. How do you #define a position? Is that just some hardcoded global coordinates the function expects?

To me most of these act as a "parameter" which is generally dynamic. I generally don't have usecases where it makes sense to define a hardcoded position, my view is generally along the lines of it's an arbitrary thing that the called function does not know, even if it is currently only called with a specific parameter. That would allow to extract parts of a datapack into a utility datapack later on. For example, if you have a utility datapack that needs to place a sign somewhere, you could annotate that function with @context position A safe position, where this function is allowed to place temporary arbitrary blocks I like to use that approach everywhere in my pack, even if the underlying position might be hardcoded somewhere within the same pack.

I also avoided execute temology intentionally. The function does not care if the rotation is gained by rotated as, facing an absolute number a relative offset or some mixture of those. Same goes for at and positioned. Using @position or @context position with a description that makes it clear what you use it for is better in my opinion than telling you how to implement context, as that may change at some point. And it avoids things like @at @s followed by @positioned ~ ~1 ~. It could even be argued that instead of position location should be used, to be able to declare a dimension there as well and drop the dimension one, as at also changes dimension data