The Bedrock Script API is the most powerful tool available to Bedrock mod creators, and also the most misunderstood. People either think it can do everything ("just script it!") or nothing ("Bedrock doesn't support real modding"). The truth is somewhere in the middle — but closer to "everything" than most people realize.
This article maps out exactly what @minecraft/server and its companion modules can and can't do as of late 2025, with practical examples for each capability.
The Core Module: @minecraft/server
This is the main scripting module. It runs JavaScript (TypeScript-compatible) in a sandboxed environment inside the Bedrock engine. Scripts execute server-side, meaning they work in single-player, multiplayer, and on Realms (with some restrictions).
Scripts are loaded from your behavior pack's scripts/ folder and declared in the manifest.json with a script module entry. They run continuously while the world is loaded.
What You CAN Do
Event Handling
The event system is the backbone of scripting. You can listen for and respond to almost every game action:
- World events:
world.beforeEventsandworld.afterEventsgive you hooks into block breaks, block placements, entity spawns, entity deaths, item use, chat messages, explosions, piston activations, weather changes, and more. - "Before" events are cancelable. You can prevent a block from being broken, stop an entity from spawning, cancel damage, or block chat messages. This is huge for creating custom rules and restrictions.
- "After" events are informational. They fire after the action happened. Use them for logging, triggering secondary effects, or updating custom systems.
- Tick events:
system.runInterval()andsystem.runTimeout()let you run code on a timer. This is how you build persistent systems like temperature tracking, thirst bars, or custom AI loops.
Example: Cancel block breaking in a specific area to create "protected zones." Listen for world.beforeEvents.playerBreakBlock, check if the block is within protected coordinates, and call event.cancel = true if it is.
Entity Manipulation
Entities (mobs, players, projectiles) are fully accessible:
- Query entities: Find all entities of a type, in a location, with specific tags, or matching complex filters.
world.getDimension("overworld").getEntities({type: "minecraft:zombie"}) - Modify health and damage: Read and set health values. Apply damage from script. Create damage-over-time systems.
- Apply effects: Give any entity status effects (speed, strength, invisibility, custom effects via commands) with specific duration and amplifier.
- Teleportation: Move entities to any coordinates in any dimension. This is how custom portals and teleportation items work.
- Tags and properties: Attach custom data to entities using tags (simple labels) or dynamic properties (key-value data that persists across sessions). Store RPG stats, ownership, custom states, anything.
- Velocity and impulse: Apply forces to entities. Launch them upward, push them away, create knockback systems, build gravity guns.
- Spawn entities: Create any entity at any location. Build custom spawner systems, summoning mechanics, or procedural encounters.
- Components: Read entity components like inventory, health, movement, and more. Check what armor a player is wearing, what they're holding, their position, rotation, and velocity.
Block Manipulation
Full read/write access to blocks in loaded chunks:
- Get and set blocks: Read what block is at any coordinate. Place any block at any coordinate. Build structures programmatically.
- Block states: Read and set block states (rotation, powered state, waterlogged, age for crops, etc.).
- Raycasting: Cast a ray from any point in any direction and get the first block hit. Essential for line-of-sight mechanics, laser weapons, building tools, and detection systems.
- Bulk operations: Fill areas with blocks, replace blocks in a region, or clear sections. Useful for arena resets, terrain modification, and custom worldgen.
- Custom block interactions: Through block custom components, handle when a player interacts with, steps on, or places/destroys a custom block.
Commands from Script
Scripts can run any slash command via dimension.runCommand() or entity.runCommand(). This gives you access to everything commands can do: particle effects, sound playback, title text, scoreboard manipulation, structure placement, and more.
This is the escape hatch for anything the API doesn't expose directly. Need particles? runCommand("particle minecraft:explosion_particle ~ ~ ~"). Need sound? runCommand("playsound mob.dragon.death @a").
Custom UI with @minecraft/server-ui
The companion module @minecraft/server-ui adds form-based UI:
- Action Forms: A list of buttons. "Choose your class: Warrior / Mage / Archer." The player picks one and your script handles the selection.
- Message Forms: Two-button dialogs. "Accept this quest? Yes / No." Simple binary choices.
- Modal Forms: Complex input forms with text fields, sliders, dropdowns, and toggles. "Enter your team name: [___] Choose difficulty: [Easy/Medium/Hard] Enable PvP: [toggle]"
Forms are triggered from script (usually on item use or entity interaction) and the response is handled asynchronously. They're not as flexible as a full custom GUI, but they cover most use cases for configuration, shops, quest dialogs, and menus.
Scoreboards
Full programmatic access to scoreboards — create objectives, set scores, read scores, display on sidebar. Scoreboards are the standard way to track persistent numeric data per player or entity.
World Data
- Dynamic properties on world: Store global data (game state, settings, counters) that persists when the world is saved and reloaded.
- Time: Read and set the world time, day count, and weather.
- Player data: Read player names, positions, game modes, permissions. Detect joins and leaves.
What You CAN'T Do (Yet)
Despite the API's power, there are real limitations:
No Custom Rendering
You cannot draw custom graphics, HUDs, health bars, or overlays. The closest workarounds are actionbar text (the text above the hotbar), title text (large centered text), and scoreboard sidebars. For anything more complex, you need resource pack UI modifications — which aren't scriptable.
No Custom Models from Script
Scripts can spawn entities that use custom models (defined in resource packs), but they can't create or modify 3D geometry at runtime. Models must be pre-built in tools like Blockbench and included in the resource pack.
No File System Access
Scripts can't read or write files, make HTTP requests, or access anything outside the Minecraft sandbox. All data storage is through dynamic properties and scoreboards. No external databases, no API calls, no file I/O.
No Custom Terrain Generation
You can't create custom biomes or modify world generation through the Script API. You can place blocks after chunks load (which is slow and visible), but you can't intercept the generation pipeline.
No Direct Audio
You can play vanilla sound events and custom sounds defined in sound_definitions.json, but you can't synthesize audio, stream music, or do anything with raw audio data.
No Custom Enchantments
As of late 2025, you can't create new enchantment types through the Script API. You can apply vanilla enchantments and simulate custom enchantments through scripts (detect item use, apply custom effects), but they won't appear as proper enchantment glints or tooltip entries.
No Custom Dimensions
Scripts can teleport between the three vanilla dimensions but can't create new ones. See our guide to faking dimensions for workarounds.
Performance Constraints
Scripts run in a sandboxed environment with a watchdog timer. If your script takes too long in a single tick, it gets killed. This means you can't do heavy computation (pathfinding for 100 entities, scanning thousands of blocks) in one frame. You need to spread work across multiple ticks.
Real-World Examples of What's Been Built
To give you a sense of the Script API's practical ceiling, here's what the community has successfully built:
- Full RPG systems — classes, leveling, skill trees, quests, NPC dialogs, all running in Script API with server-ui forms
- Custom minigames — Bed Wars, Skywars, Murder Mystery, and other game modes with full lobby systems, team management, and round logic
- Economy systems — custom currency, shops, trading, auctions between players
- Custom combat mechanics — combo attacks, dodge rolls, parry systems, special abilities with cooldowns
- Building tools — copy/paste wands, fill tools, undo/redo systems, schematic loaders
- Anti-cheat systems — speed detection, fly detection, reach detection, auto-click detection
- Procedural dungeons — generated room layouts with random mobs, traps, loot, and bosses
The API's capabilities have expanded significantly with each Minecraft update. Features that were impossible a year ago are now standard. The trajectory suggests that most remaining limitations will be addressed over the next few update cycles.
Getting Started with Scripting
If you want to learn Script API development:
- Official docs: Microsoft's Bedrock documentation covers all classes and methods
- Bedrock Wiki: Community-maintained wiki with practical examples and tutorials
- TypeScript recommended: While JavaScript works, TypeScript catches errors at compile time and provides autocomplete. Use the
@minecraft/servernpm types package. - Start simple: Hello world → listen for events → modify entities → build a system. Don't try to build an RPG on day one.
Skip the Learning Curve
BlockSmith generates Script API code automatically based on your mod description. Describe the mechanics you want — "a sword that shoots lightning on right-click with a 5-second cooldown" — and the AI writes the JavaScript, hooks up the events, and packages it into a working addon. You get the Script API's power without learning the API.