# 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