flaremc 0.1.0

Flare datapack compiler framework

Flare

Flare is a modern, programmatic framework for building Minecraft datapacks natively in Python. With Flare, you can write Minecraft commands and logic using standard Python syntax, variables, conditionals, and loops, and compile them effortlessly into highly-optimized .mcfunction datapacks. Because Flare is just Python, you have the full power of the Python language and any external libraries at your disposal!

Installation

pip install flaremc

Quick Start

Create a main.py file with your datapack logic:

from flare import namespace, score

namespace("my_pack")

# Scores are automatically compiled to scoreboard operations
health = score(20)
damage = score(5)
health -= damage

if health < 10:
    print("Warning: Low Health!")

Then compile and run your code using the built-in emulator:

flare main.py --run

CLI Usage

The flare command-line tool has several useful flags:

• flare init - Initializes a basic Flare project in the current directory.
• flare <file> --watch - Compiles your datapack and watches for any file changes to rebuild automatically.
• flare <file> --run - Compiles and runs the datapack using the internal mcemu emulator.
• flare <file> --run=5 - Runs the datapack in the emulator with an automatic timeout of 5 seconds.

---

Writing Minecraft Commands Natively

Flare includes a smart preprocessor that allows you to write literal Minecraft commands directly within your Python script! You don't need to wrap them in functions or strings—just write them as you would in an .mcfunction file.

from flare import namespace, score

namespace("my_pack")

# Write raw commands natively! Flare translates them automatically.
say Hello World!
/tp @a ~ ~ ~
execute as @a run particle flame ~ ~ ~

# You can still use standard Python logic around them!
health = score(20)
if health < 10:
    title @a title "Low Health!"

---

Debugging Output (print & dbg)

In Flare, calling the standard print() function is automatically intercepted and translated into a highly-formatted Minecraft tellraw command so the output appears directly in the game chat!

If you want to debug the raw underlying Python objects, use Flare's dbg() function. It prints the raw <score object ...> string directly to your local compiler console, and simultaneously emits a raw tellraw command to the game!

from flare import score, dbg

x = score(10)

print("The value of x is:", x)  # Emits a nicely formatted tellraw command to the game!
dbg("Raw representation:", x)   # Prints raw representation to BOTH the compiler console and the game!

---

The score Object

A score represents a Minecraft scoreboard objective. Flare handles the tedious parts of allocating and managing temporary scoreboards behind the scenes.

from flare import score

x = score(100)
y = score(50)
z = x + y  # Behind the scenes, Flare generates 'scoreboard players operation ...'

Fixed Precision (fixed)

In Minecraft, scoreboards can only store integers. To work with decimal numbers, Flare scales values. You can use the fixed class to specify decimal precision natively!

from flare import fixed

# fixed[5] means the number has 5 decimal places of precision (multiplier of 1e-5)
# So 1.5 in Python will be stored as 150000 on the scoreboard.
a = fixed[5](1.5)
b = fixed[5](2.0)
c = a * b  # Flare handles all scaling math for you!

---

NBT Variables

Flare supports full, programmatic NBT data manipulation! You define the NBT type you want using nbt[type].

Basic NBT

from flare import nbt, nbtint

# Shorthand for NBT Integers
level = nbtint(5, addr="storage mypack:data Level")

# Standard generic NBT type
health = nbt[float](20.0, addr="@s Health")

Arrays and Lists

from flare import nbtintarray, nbtlist

my_array = nbtintarray([1, 2, 3], addr="storage mypack:data MyArray")
my_array.append(4)
my_array.prepend(0)

NBT Path Chaining

You can dynamically traverse NBT Compounds using standard Python dot notation or dictionary indexing!

from flare import nbtdict

player_data = nbtdict(addr="storage mypack:data Player")

# Access sub-paths dynamically
inventory = player_data.Inventory
first_slot = inventory[0]

# If your NBT key has a space, use indexing!
weird_key = player_data["Custom Key With Space"]

Note: Flare dynamically generates the string path behind the scenes (Player.Inventory[0]). Commands are only emitted when you read or write to these endpoints!

---

Avoiding Copies with ref

By default, in Flare, if you assign a variable to another variable (y = x), it generates a Minecraft command to physically copy the data from x's address to y's address.

If you just want to pass a variable around in Python without emitting a command, wrap it in a ref!

from flare import score, ref

x = score(10)

z = x       # COPIES the value. Flare emits a command to map a new variable 'z' and copy 'x'.
y = ref(x)  # NO COPY. 'y' acts as a Python reference pointing to the exact same 'x' address.

x += 5      # Modifies 'x' (now 15). Because 'y' is a ref, 'y' is also 15. 'z' remains 10.
y += 5      # Modifies 'x' again (now 20).

print(x, y, z)  # Output in game will be: 20 20 10

---

Control Flow (If, For, While)

Flare seamlessly translates standard Python control flow into execute logic and dynamically generated mcfunction blocks!

x = score(5)
y = score(10)

if x > y:
    print("X is bigger!")
elif x == y:
    print("They are equal!")
else:
    print("Y is bigger!")

# Loops
for item in my_array:
    print(item)

Compile-Time Optimization

Flare is highly optimized. It checks conditions at compile-time.

If a condition relies purely on standard Python variables (and not Minecraft score or nbt objects), Flare resolves the logic natively and never generates Minecraft commands for branches that it knows will never run!

y = 5
x = score(5)

# 'x' is dynamic, so Flare generates an 'execute if score...' command for this branch
if x > 4:
    print("Maybe!")
    
# 'y' is a static Python variable. Flare checks '5 > 4' at compile-time.
# Because it evaluates to True, Flare runs this block unconditionally and ignores the else block!
elif y > 4:
    print("Definitely!")

# This block is physically discarded and will NOT exist in the final datapack!
else:
    print("Never!")

---

Under the Hood: __icopy__ vs __iset__

Flare uses standard Python assignment (=) heavily, but it treats new and existing variables differently to prevent memory leaks and optimize command generation:

• __icopy__ (New Variables): If you type y = x and y hasn't been used yet, Flare dynamically creates a completely new Minecraft variable for y and emits commands to physically copy the data from x's address to y. This safely isolates the two variables.
• __iset__ (Existing Variables): If y is an already existing Flare variable and you want to update its value, you shouldn't use y = x (as this would try to create a new y and potentially overwrite the Python reference, losing track of your NBT structure or scoreboard address). Instead, use y[:] = x (or call y.__iset__(x) directly). This tells Flare to emit commands to update the existing address of y with the value from x!