Strata

STRATA — Optimization Framework for Bedrock

by CIServerModding

Build better addons faster. Strata gives you 19 pre-built, crash-safe modules so you can focus on features instead of reinventing the wheel.

Licensed under Apache 2.0 — free to use, modify, and distribute. Just keep the "Powered by Strata" attribution.

★ 19 MODULES ★

• Storage — Persistent JSON storage with debounced disk writes, auto-prune, and list capping
• TickBudget — Spread heavy work across ticks without lag spikes
• Queue — Task queue, process batches per tick automatically
• Scheduler — Priority-based task scheduling with delays
• Cache — In-memory cache with TTL and auto garbage collection
• Debounce — Delay calls, only the last call in a window executes
• Throttle — Limit call frequency, at most one call per N ticks
• Cooldown — Per-player, per-action cooldown tracking
• RateLimit — N calls per time window, sliding window anti-spam
• Profiler — Measure operation timing: count, total, avg, max
• Health — Server TPS monitoring, isLaggy() alerts below 15 TPS
• Memory — Dynamic property storage usage tracking and warnings
• Inventory — findItem, countItem, addItem, removeItem helpers
• Effects — Health, food, and potion effect management
• Region — Player proximity tracking in bounding boxes
• Events — Crash-safe event, interval, and timeout wrappers
• Commands — Safe command registration with try/catch
• Utils — Player lookup, duration formatting, common helpers
• Log — Prefixed console output: info, warn, error

★ CRASH-SAFE EVERYTHING ★

Every command registration, event handler, and interval is wrapped in try/catch. One failure never cascades. Errors are logged to console.warn with full context.

★ PROVEN IN PRODUCTION ★

Strata ships with 67 automated tests (/strata:test) and a proof-of-concept addon (Strataful) that exercises 17 of 19 modules in real, functional features.

★ TECHNICAL DETAILS ★

• Architecture: Single importable ES module (strata.js)
• No experiments required (stable @minecraft/server 2.1.0)
• No cheats or operator rank needed
• Compatible with Minecraft Bedrock 1.26.40+
• Crash-safe: errors logged, not thrown
• Debounced storage: batches disk writes to reduce I/O
• Apache 2.0 licensed — free for commercial use

★ HOW TO USE ★

1. Download the .mcaddon
2. Open it — Minecraft imports the behavior pack
3. Enable the Strata BP in your world settings
4. Run /strata:test to verify all 19 modules (67 tests)
5. Build your addon: copy strata.js into your scripts folder

STRATA WIKI — Build Your Own Addon

Beginner-friendly tutorial and API reference. No prior framework experience needed.

PART 1: GETTING STARTED

STEP 1 — Create your addon folder:

MyAddon_BP/
manifest.json
pack_icon.png
scripts/
strata.js (copy from Strata download)
main.js (your addon code)

STEP 2 — Write your manifest.json. Generate UUIDs at uuidgenerator.net. Set min_engine_version to [1, 26, 40] and dependency @minecraft/server version "2.1.0".

STEP 3 — Write your main.js. Import Strata and start building:

import { world, system } from "@minecraft/server";
import { Strata, Commands, Events } from "./strata.js";

system.beforeEvents.startup.subscribe(({ customCommandRegistry }) => {
Commands.register(customCommandRegistry, {
name: "myaddon:hello",
description: "Say hello",
permissionLevel: 0,
cheatsRequired: false,
mandatoryParameters: [],
optionalParameters: [],
}, (origin) => {
const player = origin.sourceEntity;
if (player) player.sendMessage("Hello from Strata!");
return { status: 0 };
});
});

Events.on(world.afterEvents.playerSpawn, (ev) => {
const player = ev.player;
if (!player || !ev.initialSpawn) return;
player.sendMessage("Welcome! Powered by Strata v" + Strata.version);
});

That's it — you now have a working addon built on Strata.

PART 2: STORAGE — Saving Data

Storage persists data across restarts. Writes are debounced to reduce disk I/O.

Save a value:

Storage.set("myaddon:score", 100);
Storage.flush(); // force immediate write
const score = Storage.get("myaddon:score", 0);

Save a list:

Storage.setList("myaddon:players", [
{ name: "Alice", wins: 10 },
{ name: "Bob", wins: 5 }
]);
const list = Storage.getList("myaddon:players");

Find, update, remove:

const entry = Storage.getEntry("myaddon:players", "name", "Alice");
Storage.upsertEntry("myaddon:players", { name: "Alice", wins: 11 }, "name");
Storage.removeEntry("myaddon:players", "name", "Bob");

Auto-cleanup:

Storage.pruneStale("myaddon:logs", "ts", 86400000); // remove older than 24h
Storage.cap("myaddon:logs", 100); // keep only last 100

Key points: Data survives server restarts. Writes debounced by default (5 ticks). Set Storage.debounceTicks = 0 for immediate writes. Call Storage.flush() to force pending writes.

PART 3: COOLDOWN — Per-Player Timers

Cooldown.set(player, "teleport", 30000);

if (Cooldown.isReady(player, "teleport")) {
// do the action
Cooldown.set(player, "teleport", 30000);
} else {
const ms = Cooldown.getRemaining(player, "teleport");
player.sendMessage("Wait " + Utils.formatDuration(ms));
}

Cooldown.clear(player, "teleport");
Cooldown.clearPlayer(player);
Cooldown.gc();

PART 4: RATELIMIT — Anti-Spam

const ok = RateLimit.try("chat:" + player.name, 5, 10000);
if (ok) {
player.sendMessage("Sent!");
} else {
player.sendMessage("Slow down! 5 per 10s max.");
}

const count = RateLimit.count("chat:" + player.name, 10000);
RateLimit.reset("chat:" + player.name);
RateLimit.gc();

PART 5: CACHE — In-Memory TTL Cache

Cache.set("stats:" + player.name, data, 30000);
const cached = Cache.get("stats:" + player.name);
if (cached) {
// fast, no disk read
} else {
const fresh = Storage.getEntry("k", "name", player.name);
Cache.set("stats:" + player.name, fresh, 30000);
}
Cache.gc();
Cache.clear();

PART 6: EFFECTS — Health and Food

IMPORTANT: Must be called inside system.run() from command callbacks.

system.run(() => {
Effects.fillHealth(player);
Effects.fillFood(player);
Effects.apply(player, "speed", 30, 1, true);
Effects.clear(player, "speed");
Effects.clearAll(player);
const hp = Effects.getHealth(player);
const food = Effects.getFoodLevel(player);
});

PART 7: INVENTORY — Item Management

Also must be inside system.run() from command callbacks.

system.run(() => {
const count = Inventory.countItem(player, "minecraft:diamond");
const found = Inventory.findItem(player, "minecraft:diamond");
const added = Inventory.addItem(player, "minecraft:bread", 5);
const removed = Inventory.removeItem(player, "minecraft:diamond", 3);
});

PART 8: REGION — Area Detection

Region.register("spawn", {
x1: -50, y1: -64, z1: -50,
x2: 50, y2: 320, z2: 50
});

Region.onEnter("spawn", (player) => {
player.sendMessage("Welcome to spawn!");
});

Region.onLeave("spawn", (player) => {
player.sendMessage("You've left spawn!");
});

Region.start(20);
const inside = Region.isInside("spawn", player);
const names = Region.getPlayers("spawn");

PART 9: PROFILER — Performance Measurement

Profiler.start("myOp");
// ... do work ...
const ms = Profiler.end("myOp");

const wrapped = Profiler.wrap("myFn", () => { /* work */ });
wrapped();

const stat = Profiler.get("myOp");
Profiler.report();
Profiler.reset();

PART 10: QUEUE — Batch Processing

const q = Queue.create("tasks", 10, 1);
q.add({ x: 10, y: 20 });
q.addAll([{x:11,y:20}, {x:12,y:20}]);

q.start((item) => { /* runs 10x per tick */ });

q.size();
q.stop();
q.clear();
q.destroy();

PART 11: HEALTH — Server Monitoring

Health.start();
const tps = Health.getTPS();
if (Health.isLaggy()) {
Log.warn("Server lagging!");
}

PART 12: EVENTS — Crash-Safe Handlers

Events.on(world.afterEvents.playerSpawn, (ev) => {
if (ev.initialSpawn) ev.player.sendMessage("Welcome!");
});

Events.before(world.beforeEvents.entityHurt, (ev) => {
if (ev.hurtEntity.typeId === "minecraft:player") {
ev.cancel = true;
}
});

const id = Events.interval(() => { /* every 20 ticks */ }, 20);

Events.timeout(() => { Log.info("After 100 ticks"); }, 100);

PART 13: COMMANDS — Safe Registration

Basic command:

Commands.register(registry, {
name: "myaddon:ping",
description: "Ping!",
permissionLevel: 0,
cheatsRequired: false,
mandatoryParameters: [],
optionalParameters: [],
}, (origin) => {
const player = origin.sourceEntity;
if (player) player.sendMessage("Pong!");
return { status: 0 };
});

Command with parameter:

Commands.register(registry, {
name: "myaddon:greet",
description: "Greet a player",
permissionLevel: 0,
cheatsRequired: false,
mandatoryParameters: [
{ name: "target", type: CustomCommandParamType.String }
],
optionalParameters: [],
}, (origin, targetName) => {
const player = origin.sourceEntity;
const target = Utils.findPlayer(targetName);
if (target) target.sendMessage(player.name + " says hi!");
return { status: 0 };
});

IMPORTANT — Restricted Execution Mode: Command callbacks run in restricted mode. You CANNOT call these synchronously: health.setCurrentValue(), player.getComponent(), new ItemStack(), container.setItem(). Wrap them in system.run(). In-memory operations (Cooldown, RateLimit, Cache, Profiler, Queue, Throttle) are safe to call synchronously anywhere.

Commands.register(registry, {...}, (origin) => {
const player = origin.sourceEntity;
Cooldown.set(player, "heal", 30000);
Profiler.start("heal");
system.run(() => {
Effects.fillHealth(player);
player.sendMessage("Healed!");
});
Profiler.end("heal");
return { status: 0 };
});

PART 14: ADVANCED PATTERNS

Full command with cooldown + effects + profiling:

Commands.register(registry, {
name: "myaddon:boost",
description: "Speed + strength (60s cd)",
permissionLevel: 0, cheatsRequired: false,
mandatoryParameters: [], optionalParameters: [],
}, (origin) => {
const player = origin.sourceEntity;
if (!player) return { status: 1 };
Profiler.start("boost");
if (!Cooldown.isReady(player, "boost")) {
player.sendMessage("CD: " + Utils.formatDuration(
Cooldown.getRemaining(player, "boost")));
Profiler.end("boost");
return { status: 0 };
}
Cooldown.set(player, "boost", 60000);
system.run(() => {
Effects.apply(player, "speed", 30, 1, true);
Effects.apply(player, "strength", 30, 1, true);
Effects.fillHealth(player);
player.sendMessage("Boosted!");
});
Profiler.end("boost");
return { status: 0 };
});

Persistent stats with debounced saving via Queue:

const q = Queue.create("stats", 5, 20);
q.start((item) => {
let s = Storage.getEntry("stats", "name", item.name)
|| { name: item.name, joins: 0 };
s[item.field] = item.value;
Storage.upsertEntry("stats", s, "name");
});
q.add({ name: player.name, field: "joins", value: 1 });

Periodic GC every 5 minutes:

Events.interval(() => {
Cache.gc();
Cooldown.gc();
RateLimit.gc();
Storage.flush();
}, 6000);

PART 15: QUICK REFERENCE

Importing Strata:

import {
Strata, Log, Storage, TickBudget, Debounce,
Throttle, Cache, Events, Health, Commands, Utils,
Profiler, Queue, Scheduler, Cooldown, RateLimit,
Memory, Inventory, Region, Effects
} from "./strata.js";

Cheat sheet:

Log.info("msg") — console log
Storage.set("key", val) — save (debounced)
Storage.get("key", fallback) — read
Storage.getList("key") — read JSON array
Storage.upsertEntry(k, e, f) — add/update entry
Storage.pruneStale(k, f, ms) — remove old entries
Storage.flush() — force writes
Cache.set("k", v, ttlMs) — cache with TTL
Cache.get("k") — read cache
Cooldown.set(p, "k", ms) — start cooldown
Cooldown.isReady(p, "k") — check if ready
RateLimit.try("k", max, ms) — check rate limit
Effects.fillHealth(p) — heal to full
Effects.fillFood(p) — fill food
Effects.apply(p, eff, dur, amp) — potion effect
Inventory.countItem(p, typeId) — count items
Inventory.addItem(p, typeId, n) — give items
Region.register("name", bounds) — create area
Region.onEnter("name", cb) — enter callback
Profiler.start("label") — start timing
Profiler.end("label") — stop timing
Profiler.report() — all stats
Queue.create("name", batch, t) — task queue
Scheduler.init() — start scheduler
Scheduler.schedule(fn, delay) — delayed task
Health.getTPS() — server TPS
Utils.findPlayer("name") — find player
Utils.formatDuration(ms) — "30s", "2m", "5h"
Commands.register(reg, spec, cb) — safe command
Commands.list() — registered commands
Events.on(signal, cb) — after-event
Events.before(signal, cb) — before-event
Events.interval(cb, ticks) — safe interval

IMPORTANT RULES:

1. Native API calls (health, food, inventory, effects) MUST be inside system.run() from command callbacks.
2. In-memory ops (Cooldown, RateLimit, Cache, Profiler, Queue, Throttle) are safe synchronously anywhere.
3. Storage writes are debounced. Call Storage.flush() to force writes.
4. Every command registration is crash-safe.
5. Every event handler is crash-safe.
6. You MUST display "Powered by Strata" in your addon credits per the Apache 2.0 NOTICE file.

★ CREDITS ★

Publisher: CIServerModding
Developer: ClockSplice
Framework: Strata v0.3.0 (2026.0.3.0)
License: Apache License 2.0

★ BUG REPORTS & FEATURE REQUESTS ★

Found a bug? Want a module added? Let me know in the comments!

Powered by Strata — Optimization Framework for Bedrock
© 2026 CIServerModding. Apache License 2.0.