arcensoth / imp-spec

IMP: Interoperable Module Protocol design specification and recommendations for Minecraft datapacks.

IMP: Interoperable Module Protocol

IMP is a design specification for Minecraft datapacks, including a set of core compliance standards as well as additional recommendations and formatting guidelines.

• IMP Core Standards (IMP-Core)
• IMP Conventions & Recommendations (IMP-Con)
• IMP Documentation Format (IMP-Doc)

imp-spec's Issues

Extend @context for more than just entities

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

@within should explicitly allow @private access

From the current specification, it is unclear whether a function with a @within visibility is allowed to call itself.

However, it happens commonly for me, that I need a loop that is tailored to be used in a specific function and should not be used elsewhere.
Dph+ follows the specification in that regard and errors when I try to call a @within-defined function from within itself so I commonly end up with things like these:

#> 91:loop
# ...
# @within
# 	function 91:parent
# 	function 91:loop

I would like to avoid this and generally think it is weird to be able to make a function invisible for itself.

Scoreboard 16-char limit removed in 21w37a

This IMP-Core section needs updating: Namespace scoreboard objectives

In snapshot 21w37a/Changes/General/Scoreboards:

Removed length limits for scoreboards, score holders and team names.

Options:

1. Only current release: Delete the things about scorespace (abbreviating) and describe it like in other sections (with full-namespaces)
2. Backward compatible: Make(and move current text to) an additional comment/section like "Prior to 1.18 (21w37a): ..."

Does it make sense to use $path/to/function.score_holder in temporary objectives?

This is a similar idea as the recommendation on how to name storage locations for transient storages, just applied to scoreboard players.

I generally like having only one temporary objective, since objective names are far more limited in size than scoreboard player names (16 vs 40).
Because of that, I often run into annoyances where I accidentally re-use a player name from an outer function.

Because of that, I came up with the idea to use a path/to-pattern for player names in globally used temporary objectives.
I don't think it's a good solution to use more scoreboard objectives instead, since you'd probably end up with a scoreboard per "area"/sub-dir or whatever. The problem I am describing however happens most commonly between functions that call each other of the same sub-dir.

So I simply define a namespace.temp objective and the player names within that are called either entirely accurately like the path of the function, or uses short forms to still fit within the character limit.
Furthermore, for variables that are meant to be "global" within a subdir, I only use the path/to/subdir naming.
I separate the actual name of the player name using a dot (.).
It is not necessary to namespace player names, since they are located within an already namespaced scoreboard objective.

Does that make sense and should it perhaps be included in this repository's recommendations?

Standardize documentation for things other than functions

The current IMP doc only covers documentation for functions.
There are already some extensions to this, for example by Datapack Helper Plus.

I think it would be good to come up with a standard for this before we get more conflicting standards.

Things I think are worth to be documented:

• Scoreboard objectives
• Scoreboard players
• Storages (as in the namespaced ID of a storage)
• Bossbars
• Tags (as in tags inside an Entity's Tags:[] nbt-tag)
• Teams
• All sorts of JSON files

Currently, IMP doc has to be in the first line of a function file. For non-function file declarations that doesn't make sense, of course. There are several ways such definitions could be applied.

Right where you execute a defining command

This would still be a function comment and is basically what dph+ does.

Since for functions the first line has to include the function's name, I think it would make sense for other things to do the same.
To be able to know what is defined, I propose using a prefix to the resource location (which is optional for function definitions for backwards compatibility)

Example

#> scoreboard 91.ns.main
# The main storage of this data pack
# @internal
scoreboard objectives add 91.ns.main

Considerations

While this works well for things that are actually defined with a single command, such as objectives, bossbars and teams, other things datapacks use are not defined in such a way, including tags, scoreboard players, storages or any JSON definition.

In order to mitigate this, the restriction that the IMP doc has to appear right above the definition could be removed in this case

In a separate file

With this idea, definitions could be put into a separate file (with a custom extension such as .imp or .impdoc.
A file could hold multiple such definitions. This might be nice for giving a good overview of a specific directory, for example, such a file could be present in a namespace/advancements/... directory.

Example

> advancement namespace:technical/detect_kill
Detects a player killing another entity and runs the function namespace:detection/player_kill
@within function namespace:detection/player_kill

> advancement namespace:technical/in_water
Detects a player entering a water source block and runs the function namespace:detection/enter_water
@within function namespace:detection/enter_water

Considerations

While this might be nice for some things, like giving an overview of declarations in a datapack, It would also allow to separate different definitions, for example by declaring a tags.impdoc including all tags. I don't think it should be the only way. Thinking of e.g. java this feels more like an exported form of Javadoc (or impdoc in this case) instead of an in-code documentation

In a non-vanilla JSON tag (for JSON definitions only)

Pretty self-explanatory, just add a custom JSON tag at the beginning of a JSON file

Example

{
	"_impDoc": {
		"description": "Detects a player killing another entity and runs the function namespace:detection/player_kill"
		"within": {
			"type": "function",
			"value": "namespace:detection/player_kill"
		}
	},
	// ... (advancement definition here)
}

Considerations

I think this works pretty well and should be possible for anything that's defined as JSON, but of course does not work for anything else, so another solution is needed for those cases.

Anything else?

Feel free to add/ discuss other ideas here