JsMacros Coding Assistant Guidelines

Understanding the JsMacros Context

• JsMacros uses GraalJS for JavaScript execution within Minecraft
• This is NOT Node.js or browser JavaScript - it's JavaScript embedded in Java via GraalVM
• Focus on simple, basic JavaScript - avoid complex patterns or ES6+ features when not necessary
• No access to npm packages or external JS libraries
• Code must be simple, focused, and compatible with the JsMacros environment
• When unsure about API functionality, explicitly note this in comments

JavaScript Approach

• Use simple, straightforward JavaScript - prioritize readability over sophistication
• Prefer basic JavaScript constructs that are widely compatible
• Avoid complex destructuring, arrow functions, or advanced JS features unless necessary
• Focus on functional solutions rather than elegant but complex code
• Remember the purpose is Minecraft scripting, not advanced JS application development
• Use Chat.log("") for printing to Minecraft chat/console instead of console.log()

Java Interoperability

• Use Java.type("fully.qualified.ClassName") to access Java classes
• When Java.type doesn't work, use the Reflection library
• Be aware that JavaScript in JsMacros has limited capabilities compared to Node.js
• No access to Node.js built-in modules
• Use Java alternatives or pure JS implementations when needed
• To search for Minecraft classes (not JsMacros), use keywords: "fabric maven yarn api" plus the class name
• Minecraft classes use 'intermediary' names (not 'official' or 'named') which may look obfuscated
• Example: For BlockPos, search for "fabric maven yarn api BlockPos" and use intermediary name:

''' const BlockPos = Java.type("net.minecraft.class_2338"); new BlockPos(...) '''

Code Formatting

• Use consistent 2-space indentation for JavaScript
• Keep code simple and readable - prefer clarity over clever solutions
• Use blank lines to separate logical sections of code
• Include descriptive comments for non-obvious code sections

Best Practices for JsMacros

• Focus on the specific Minecraft interaction being scripted
• Handle errors gracefully to prevent script crashes
• Use appropriate event listeners for Minecraft events
• Document script purpose and usage at the top of each file
• Check the JsMacros documentation before suggesting complex solutions

Common JsMacros Script Patterns

One-time Script

• Executes once and completes. Simple straight-through execution:

''' // Simple one-time script example Chat.log("Starting task..."); // Do something const playerPos = Player.getPlayer().getPos(); Chat.log("Current position: " + playerPos.x + ", " + playerPos.y + ", " + playerPos.z); Chat.log("Task completed!"); '''

Toggle Script with Background Process

• Uses GlobalVars to maintain state between executions:

''' const name = "ToggleScript"; // the name of the script const enabled = GlobalVars.toggleBoolean(name);

Chat.log(name + " " + (enabled ? "enabled" : "disabled"));

while (GlobalVars.getBoolean(name)) { Chat.log("do stuff here..."); Client.waitTick(20); // wait 20 tick = 1 sec } '''

Event-Based Persistent Service

• Services start with Minecraft and are meant to be persistent:

''' // Service that displays current TPS JsMacros.assertEvent(event, "Service"); const d2d = Hud.createDraw2D(); let tpsmeter = null; d2d.setOnInit(JavaWrapper.methodToJava(() => { tpsmeter = d2d.addText(World.getServerTPS(), 0, d2d.getHeight() - 10, 0xFFFFFF, true); })); const tickListener = JsMacros.on("Tick", JavaWrapper.methodToJava(() => { tpsmeter?.setText(World.getServerTPS()); })); d2d.register();

// this fires when the service is stopped event.stopListener = JavaWrapper.methodToJava(() => { d2d.unregister(); JsMacros.off(tickListener); }); '''

When Documentation is Missing

• Clearly mark uncertain code sections with // TODO: Verify this approach
• Provide alternative approaches when unsure about the correct implementation
• Explicitly state assumptions made when documentation is incomplete
• Suggest consulting the official JsMacros documentation for confirmation

Documentation References

• When available, refer to the official JsMacros documentation
• Link to specific documentation pages when suggesting implementations
• If documentation doesn't cover a topic, clearly indicate this