LegacyScriptEngine API: entities
In LSE, I want the damage source of pl.hurt(damage[,type[,source]]) to be another player. Can I pass a Player object directly? What is the difference between Player and Entity objects, and how do I convert a Player to an Entity?
LSE's Player object (runtime class name LLSE_Player) contains most of the methods and properties of Entity, but it is a different type. For interfaces that need an Entity argument, use pl.toEntity() to convert the player to an entity object (it returns null if the conversion fails); toEntity has long been available.
In the current version, the source parameter of pl.hurt / en.hurt accepts both Entity and Player objects internally, so you can call target.hurt(damage, ActorDamageCause.EntityAttack, attackerPlayer) directly; passing attackerPlayer.toEntity() also works. If you need vanilla damage calculation (armor reduction and so on), you can also use a command:
mc.runcmdEx(`execute as "<attacker>" run damage <target> <amount> entity_attack entity @s`)Applies to: LSE 0.23.x
entity.hurt() in LSE needs an integer damage type. How do I get the enum values? Can the cause from the onMobHurt event be passed straight to hurt()?
LSE registers a global damage cause enum object DamageCause (and keeps ActorDamageCause with the same content for compatibility). Keys are the enum names and values are ints, and you can use them directly, for example pl.hurt(1.0, ActorDamageCause.Fire) or pl.hurt(1.0, DamageCause.Fire). The signature of hurt is hurt(damage, type?, source?). The cause parameter of the onMobHurt callback is the integer value of this enum and can be passed straight to hurt(). The enum definition in the LeviLamina source src/mc/deps/shared_types/legacy/actor/ActorDamageCause.h is authoritative (the enum table in the docs may be incomplete).
Applies to: current LSE version
In LSE, entity.name/getName returns the untranslated key for Addon mobs (even though the resource pack's zh_CN.lang has a translation). How do I translate the entity name into a given language?
The cause is that since 1.19.80 BDS has changed the loading order: the server I18n loads before resource packs, so the server only loads the vanilla language files, and the language files in Addon resource packs never enter the server I18n. Options:
- For vanilla entities, take the entity
type(such asminecraft:zombie), remove the"minecraft:"prefix to form the language keyentity.<name>.name(such asentity.zombie.name), and translate that. - Install the third-party GMLIB. Its built-in I18nFix corrects the loading order (disabled by default; it must be enabled through the C++ interface or by a plugin that depends on it). Alternatively, use the interface provided by GMLIB-LRCA to load the resource pack's
zh_CN.langinto the server I18n manually; after that, interfaces that use server-side translation, such asentity.name, return the Chinese name directly. - Parse the resource pack's
.langfiles yourself and build a mapping, or use LSE's built-ini18n.loadto load your plugin's own translation files and translate withi18n.tr/trl(note that this is the plugin's own translation system, not BDS's I18n).
Applies to: BDS 1.19.80 and later; GMLIB-related options are third-party plugins. Not confirmed against the source code or the documentation: treat it as a pointer.
In an LSE JS plugin, using an entity object as a Map key or comparing two entity objects with == fails to find or match them. What should I do?
Every entity/player object that LSE returns is a newly created JS wrapper object with no custom equality logic, so comparing them directly with ==/=== or using them as Map keys never matches. Use the entity's uniqueId as the key or comparison basis, for example Boss.find(entity => entity.uniqueId == mob.uniqueId).
Which parameters does entity.distanceTo() accept in LSE? Passing pos.x/pos.y/pos.z gives a parameter type error or too few arguments. What should I do?
With one parameter, distanceTo accepts an IntPos, FloatPos, Player or Entity (pass a position object such as player.pos directly, without splitting it into .x .y .z). Otherwise you must pass 4 numeric parameters: x, y, z, dimid (passing only 3 gives a parameter count error). For example:
const pos = player.pos;
if (entity.distanceTo(pos) > R) { /* ... */ }If the target is in a different dimension than the entity, the return value is a very large number (INT_MAX). Player also has a distanceTo with the same name, plus the alias distanceToPos.
In LSE, why does checking whether an entity is a player with entity.isPlayer (without parentheses) always succeed?
isPlayer is a function, so write entity.isPlayer() (with parentheses, like pl.isOP()). Without parentheses you are testing the function object itself, which is always truthy because the function exists.
In LSE, how do I convert an entity object (Entity) to a player object (Player)?
Use en.toPlayer(). It returns null if the entity is not a player or the conversion fails, so you can check with en.isPlayer() first. This API is on the "Entity" page of the docs, and you can also find it in the d.ts type definitions in the legacy-script-engine-api repository (GameAPI/Entity/Entity.d.ts). For the reverse direction, use pl.toEntity().
In LSE, how do I open a menu when a player right-clicks (interacts with) or left-clicks (attacks) an entity?
For right-click interaction, use the onPlayerInteractEntity event, added in LSE 0.9.5:
mc.listen("onPlayerInteractEntity", (pl, en, pos) => {
if (en.type == "minecraft:entity_id") {
pl.runcmd("command that opens the menu");
}
});Interaction means a right mouse click, a long press on a touch screen, or pressing the interact button on the entity.
For left-click attacks, use onAttackEntity(player, entity), or onMobHurt:
mc.listen("onMobHurt", (m, s, d, c) => {
if (s && s.isPlayer() && m.type == "minecraft:entity_id") {
s.toPlayer().runcmd("command that opens the menu");
}
});Note that the source of onMobHurt may be null, so check it first.
Applies to: LSE 0.9.5 and later
Does the LSE JS plugin API have an interface for spawning or handling experience orbs?
There is no dedicated experience orb interface, but you can use the generic entity spawning interface: mc.summonMob("minecraft:xp_orb", pos) (it takes the same path as /summon and is available since 0.19.1) spawns the orb and returns an Entity object, which you then handle with the entity API. You can also use mc.runcmdEx("summon xp_orb x y z"). See the entity API page for details: https://levimc.org/LegacyScriptEngine/apis/GameAPI/Entity/.
Applies to: LSE 0.19.1 and later (summonMob)
How do I generate loot (drops) for a mob in an LSE script?
LSE has no direct loot table API. The options are:
- Spawn an entity of the same type with
mc.spawnMob(type, pos), then kill it withentity.hurt(damage[, type[, source]])so it drops items. - Use the vanilla
/lootcommand (mc.runcmd). The source can be an entity (kill) or a loot table (loot), and you can combine it withmainhandand similar options to simulate killing with a tool (such as Looting). - Read the loot table json yourself and compute the drops.
- Implement it in a C++ mod and export it to scripts.
Not confirmed against the source code or the documentation: treat it as a pointer.
How do I apply an impulse or velocity to a player in LSE (like applyImpulse in ScriptAPI)?
Use setPosDelta on Entity: player.toEntity().setPosDelta(x, y, z), or pass a FloatPos with en.setPosDelta(delta). It sets the entity's per-tick position change (its motion), works on players as well, and returns whether it succeeded.
In LSE, calling mc.spawnMob inside a mob spawn event callback causes an infinite loop / stack overflow and crashes the server. Why, and how do I avoid it?
mc.spawnMob calls the Level's Spawner (BedrockSpawner) spawnMob underneath, which is the same logic as natural spawning. The mob spawn event (onMobTrySpawn, formerly onMobSpawn) hooks exactly this function, so calling spawnMob again in the callback triggers the event again and recurses forever.
Solutions:
- Guard against re-entry with a flag variable: when the event fires, return immediately if the flag is
true; otherwise set it totrue, spawn the entity, then set it back tofalse. - Or use
mc.summonMob, added in LSE 0.19.1. It uses the spawn logic of the summon command and does not go throughSpawner::spawnMob, but the spawned entities are made persistent and never despawn naturally, so be careful with heavy use.
Also, the entity does not exist yet when the spawn event fires, so adding a tag afterwards to identify it does not work. If you only want more mobs to spawn, it is better to change the herd size in spawn_rules with a behavior pack.
Applies to: LeviLamina + LegacyScriptEngine current version (mc.summonMob requires LegacyScriptEngine 0.19.1 or later)
I want to disable almost all entity spawning with LSE (including spawn eggs, commands, etc.). Can LSE do that?
What LSE can intercept is mob spawning that goes through Spawner::spawnMob:
onMobTrySpawn:return falseto intercept. The documentation describes it as "an entity attempts to spawn naturally", but it actually hooksBedrockSpawner::spawnMob, so non-natural paths such as LSE's ownmc.spawnMobalso trigger it. Whether spawn eggs and other paths go through this function needs to be tested yourself.onMobSpawned: a notification after spawning completes; it cannot be intercepted.- For projectiles, use
onSpawnProjectile.
/summon does not go through spawnMob (its spawn logic lives in the anonymous-namespace function CommandUtilsAnon::_spawnEntityAt), so intercepting it requires a native C++ hook. Deleting the entity registrations directly is possible in theory, but it is too invasive and may cause plugin conflicts and other problems, so it is not recommended.
Applies to: LegacyScriptEngine current version
How do I attach custom data to an entity (like custom NBT on an item), and how do I get a single entity by uniqueId in LSE?
You can take the entity's uniqueId and store the data in the plugin's own data file, or add a tag to the entity with en.addTag(tag) (Actor::addTag in C++). To get a single entity by uniqueId: since LSE 0.9.5 there is mc.getEntity(id), whose parameter is the entity's UniqueId or RuntimeId; it returns null on failure. You can also iterate with mc.getAllEntities() / mc.getEntities(...) and search.
Applies to: LegacyScriptEngine 0.9.5 and later
I want a mob to be visible only to a specific player and attack only that player. Can an LSE JS plugin do this?
"Visible only to a specific player" can be done by intercepting or customizing the packets sent to the client (using native packet-related capabilities or a plugin). But checking or controlling a mob's locked attack target cannot be done in JS, because LSE completely removed NativeAPI long ago; you need to implement it with a native C++ mod.
Applies to: LegacyScriptEngine 0.8.19 and later
Can LSE get all entities to clean up entities in unloaded chunks? How do I get all entities in C++?
No. In LSE, use mc.getAllEntities() to get all entities (mc.getEntities(pos...) queries by coordinate range). Both return only loaded entities and cannot reach entities in unloaded chunks, so a script cannot clean up unloaded entities. In a C++ mod, you can get all entities (again, loaded ones only) with Level::getRuntimeActorList() or Level::getEntities().
Applies to: LSE / LeviLamina current version