Tags (New System, Post 1.7.10) - ProjectZulu/JustAnotherSpawner GitHub Wiki

JAS uses a Tag system powered by MVEL scripts to allow end users to customize JAS behaviour.

Importing Old Tags
Behaviours
Behaviour examples

MVEL script tags
Variables
Common functions
Legacy tag functions
Objective functions
Utility functions
World access functions
Count access functions
Time functions

This section only applies if you're converting old configurations to the new system. Skip ahead otherwise.

Tags have been replaced with MVEL expressions. These are scripts based on Java syntax. See https://en.wikisource.org/wiki/MVEL_Language_Guide

Old tags are imported from fileVersion=1.0 config files and automatically converted to the new expression format. The format is similar: {spawn:sky} is now just sky().

• Old CreatureType Monster Tag: "Tags": "{spawn:!solidside,1,0,[0/-1/0]:liquid,0:normal,0:normal,0,[0/1/0]:!opaque,0,[0/-1/0]}"
• New CreatureType Monster Tag: "Spawn Tag": "!solidside(1,{0,0,0},{0,-1,0})||liquid({0,0,0},{0,0,0})||normal({0,0,0},{0,0,0})||normal({0,0,0},{0,1,0})||!opaque({0,0,0},{0,-1,0})"

All MVEL expressions are on their own 'line'. They no longer split from a single line i.e. {spawn}{depsawn} MVEL supports brackets, if-else statements, ternary operator, ^, &&, ||. Note that if using " that because " is considered special is GSON it must be escaped i.e. "Entity Tags": ""Zombie"", needs to be "Entity Tags": "\"Zombie\"".

MVEL automatically assumed the result of the expression based on the output i.e. sky() && blockfoot() is clearly a boolean result and MVEL will handle it automatically. There are functions ('tags') that will not return a boolean function. i.e. count.getLocalEntityTypeCount(String entityType) returns an integer. To be valid it must be compared to something i.e. count.getLocalEntityTypeCount(String entityType) < 5.

Tags can be attached to CreatureType, LivingHandler, and SpawnList entries. The behaviour effected depends on the field the tag is attached to. Each entry type does not support all of the aforementioned behaviours.

The following is an overview of the tags. Beginners will want to start at the Example configuration files for in-depth explanations with examples.

Entry Type	Field	Rtn Value	Effect
CreatureType	"Spawn Tag"	Boolean [***]	Whether Entity of the TYPE's spawning should be interrupted. i.e SPAWN entity unless EXPRESSION is TRUE
LivingHandler	"Spawn Tag"	Boolean [***]	Whether Entity's spawning should be interrupted. i.e SPAWN entity unless EXPRESSION is TRUE [**]
	"Despawn Tags"	Boolean [***]	Whether Entity's despawning should be interrupted. i.e DESPAWN entity unless EXPRESSION is TRUE
	"PostSpawn Tags"	Boolean [***]	Used to writeNBT data after immediately after an entity is spawned [*].
	"Entity Tags"	Boolean [***]	Used to writeNBT data after immediately after an entity is spawned [*].
	"Entity Tags"	String [***]	Overrides what Entity this LH should spawn. Expects a String value, a JAS entity mapping.
SpawnListEntry	"Spawn Tag"	Boolean [***]	Whether Entity of the this BIOMEGROUP's spawning should be interrupted. i.e SPAWN entity unless EXPRESSION is TRUE [**]
	"PostSpawn Tags"	Boolean [***]	Used to writeNBT data after immediately after an entity is spawned [*].

[*] : Note that writeNBT can be done during the Spawn Tag for MOST entities. MoCreatures entities were the reason this capability was added.

[**] : LivingHandler and SpawnListEntry conditions are combined with either OR or AND depending on the value of the LivingHandler "Spawn Operand"

[***]: Absent if empty

#	Example Tag	Interpretation
1	"Spawn Tag": "true"	Entity should spawn
2	"Spawn Tag": "false"	Entity should not spawn
3	"Spawn Tag": "sky()"	Entity should spawn unless it can see sky
4	"Spawn Tag": "!sky()"	Entity should spawn unless it can see not sky

MVEL scripts are scripts based on Java syntax. See https://en.wikisource.org/wiki/MVEL_Language_Guide Guide for 2.0. Typically a script is composed of several of the functions listed below combined using && (AND) or || (OR). i.e. solidside(1,{0,0,0},{0,-1,0})||liquid({0,0,0},{0,0,0}).

Common Elements

• Integer elements are simply a number i.e. 1
• Boolean True and False are reserved keywords true and false respectively
• Equality operator to compare if two numbers are equal is == i.e. sky()==true
• Not operator, to reverse a boolean value is ! i.e. !sky()
• OR operator is simply || i.e. solidside(1,{0,0,0},{0,-1,0})||liquid({0,0,0},{0,0,0}).
• AND operator is simply && i.e. solidside(1,{0,0,0},{0,-1,0})&&liquid({0,0,0},{0,0,0}).
• Strings are marked using Single quotation marks '' i.e. 'Skeleton'.
• Arrays are marked using by curly opening and closing braces and a comment between each element i.e. Three integer elements would be {1,2,3}

Access to the following methods are provided and accessed in the form "Spawn Tag": "sky()". If a specific size array is marked with the form [N] where N is the number of values required. If unlimited it will say N. Typically 3 and that means X,Y,Z coords/range/offsets. If 2 it would mean min/max or X/Z (i.e. biomes which are same no matter Y).

The methods listed below are in the form ReturnValue functionName(arg1Type argument1, arg2Type argument2, etc). Arguments are values provided by the user that must be of the stated type. It it used by placing the script with the functionName with the desired arguments in brackets seperated by commas. i.e. To check if 2 players are in range from 30 to 40 we would want to use the function int obj.playersInRange(int minRange, int maxRange) which in the script form would be "obj.playersInRange(30,40)==2".

Access to the following fields are variables are provided and accessed in the form "Spawn Tag": "posX > 200"

• posX: X coordinate of the spawning location
• posY: Y coordinate of the spawning location
• posZ: Z coordinate of the spawning location
• entity: The entity to be spawned (not present during CreatureType processing)

These functions are all deprecated and will eventually be removed. Equivalent functions have been created Ctrl+F the function name to find its replacement. Boolean functions check if a condition is true or false, and return that state.

• boolean [sky|ground_and_sky]
• boolean [ground|ground_and_sky]
• boolean block(String[N] blockKeys, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean block(String[N] blockKeys, Integer[N] metas, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean blockFoot(String[N] blockKeys)
• boolean blockFoot(String[N] blockKeys, Integer[N] metas)
• boolean normal(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean liquid(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean opaque(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean solidside(Integer side, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean random(int range, int offset, int maxValue) // True if [0, range - 1] + offset <= maxValue
• boolean [modspawn] // Calls default entity.getCanSpawnHere methods
• boolean [isTamed|tamed_tameable]
• boolean [isTameable|tamed_tameable]
• boolean biome(String biomeName, int[3] range, int[3] offset) // BiomeName can be G|group, A|attribute, or mapping.
• boolean writenbt(String[] nbtOperations)

Plenty of old-style tag equivalents that are less useful now that expressions can be made on the users own

• boolean lgcy.height(int minHeight, int maxHeight)
• boolean lgcy.light(int minLight, int maxLight)
• boolean lgcy.torchlight(int minLight, int maxLight)
• boolean lgcy.origin(int minDistance, int maxDistance)
• boolean lgcy.height(int minHeight, int maxHeight)
• boolean lgcy.top() // Block at foot is same as biomes specified top block
• boolean lgcy.filler() // Block at foot is same as biomes specified filler block
• boolean lgcy.dimension(int dimension)
• boolean lgcy.location(int[3] offset, int[3] range)
• boolean lgcy.players(int[2] searchRange, int[2] minMaxBounds)
• boolean lgcy.entities(String[N] searchNames, int[2] searchRange, int[2] minMaxBounds)
• boolean lgcy.difficulty(int desiredDifficulty)
• boolean lgcy.random(int range, int offset, int maxValue) // True if [0, range - 1] + offset <= maxValue

These do not generally return boolean values, but quantities of values at spawn location

• String obj.block() // returns name of block
• int obj.light() // returns light level
• int obj.torchlight()
• int obj.origin() // Distance to Server-spawnpoint
• String obj.material()
• int obj.difficulty // 0 == Peaceful, 1 == Easy, 2 == normal, 3 == Hard
• int obj.highestResistentBlock() // Highest block that restrics movement and is not Leaves, wood, glass, or foliage
• int obj.playersInRange(int minRange, int maxRange) // Number of players in sphere specfified by min/max range
• int obj.countEntitiesInRange(String[N] searchNames, int minRange, int maxRange) // Number of players in sphere specfified by min/max range, searchName is FML name
• int obj.countJASEntitiesInRange(String[N] searchNames, int minRange, int maxRange) // Number of players in sphere specfified by min/max range, searchName is JAS name
• boolean obj.sky()
• boolean obj.ground()

Less useful tags used by other tags internally or by advanced users

• boolean util.inRange(int current, int minRange, int maxRange) // Is the current value between the min and max
• String util.material(Material material) // String name for the provided Material reference
• int util.rand(int value) //random value between 0 and value-1
• void util.log(String string) // Logs measage to FML log under [JAS] header. Is prepended with [TAG_LOG]

Access to certain function similar to native world functions modders have access to. Used to check arbitrary nearby blocks to spawn position.

• int wrld.lightAt(int coordX, int coordY, int coordZ)
• int wrld.torchlightAt(int coordX, int coordY, int coordZ)
• String wrld.blockNameAt(Integer offsetX, Integer offsetY, Integer offsetZ)
• Block wrld.blockAt(int coordX, int coordY, int coordZ) // returns Block object at coord
• Block wrld.biomeTop(int coordX, int coordZ) // returns Block object of specified top block of Biome at coord
• Block wrld.biomeFiller(int coordX, int coordZ) // returns Block object of specified filler block of Biome at coord
• BiomeGenBase wrld.biomeAt(int coordX, int coordZ) // returns Biome object at coord
• Material wrld.materialAt(int coordX, int coordY, int coordZ) // returns Material object at coord
• ChunkCoordinates wrld.originPos() // Server Spawn point
• boolean wrld.skyVisibleAt(int coordX, int coordY, int coordZ) // call to World.canBlockSeeSky(int coordX, int coordY, int coordZ)
• int wrld.dimension() // Current Dimension, 0 == overworld
• long wrld.totalTime() // Total time for the world
• long wrld.timeOfDay() // The current world time in ticks, ranging from 0 to 23999. See http://minecraft.gamepedia.com/Day-night_cycle for time periods.

Access to the current entity count

• int count.getLocalEntityTypeCount(String entityType) // Number of CreatureType in the current chunk
• int count.getLocalEntityClassCount(String entityJasName) // Number of JAS mapping in the current chunk
• int count.getGlobalEntityTypeCount(String entityType) // Number of CreatureType across countable chunks
• int count.getGlobalEntityClassCount(String entityJasName) // Number of JAS mapping across countable chunks
• int count.entitiesSpawnedThisChunk() // Counts all entities spawned during all "Iterations Per Chunk" CreatureType settings
• int count.entitiesSpawnedThisPack() // Counts all entities spawned during all "Iterations Per Pack" CreatureType settings
• int count.clodCount(String entityType) // Number of CreatureType in a 2x2 chunk radius, same area used in BiomeCap

• int time.timeOfDay(); // Time of the day between [0, 24000)
• boolean time.isMidnight(); // 1 Hour before & after 18000
• boolean time.isAfternoon(); // 1 Hour before & after 6000
• boolean time.isDawn(); // 1 Hour before & after 0000
• boolean time.isDusk(); // 1 Hour before & after 12000
• int time.moonPhase(); // Moon phase from [0 == Full Moon, 7 == Waxing Gibbous]
• boolean time.isFullMoon(); // Obvious names, otherwise see Minecraft wiki Day/Night Cycle
• boolean time.isWaningGibbous();
• boolean time.isLastQuarter();
• boolean time.isWaningCrescent();
• boolean time.isNewMoon();
• boolean time.isWaxingCrescent();
• boolean time.isFirstQuarter();
• boolean time.isWaxingGibbous();

• boolean block(String[N] blockKeys, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean block(String[N] blockKeys, Integer[N] metas, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean blockFoot(String[N] blockKeys)
• boolean blockFoot(String[N] blockKeys, Integer[N] metas)
• boolean normal(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean liquid(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean opaque(Integer[3] searchRange, Integer[3] searchOffsets)
• boolean solidside(Integer side, Integer[3] searchRange, Integer[3] searchOffsets)
• boolean biome(String biomeName, int[3] range, int[3] offset) // BiomeName can be G|group, A|attribute, or mapping.

SearchPattern can be "CUBE" or "HOLLOW". CUBE searches all blocks within the search able area. HOLLOW only searches the outer edge.

• boolean block(String[N] blockKeys, Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean block(String[N] blockKeys, Integer[N] metas, Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean normal(Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean liquid(Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean opaque(Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean solidside(Integer side, Integer[3] searchRange, Integer[3] searchOffsets, String searchPattern)
• boolean biome(String biomeName, int[3] range, int[3] offset, String searchPattern) // BiomeName can be G|group, A|attribute, or mapping.

• boolean ent.modspawn() // Calls default entity.getCanSpawnHere methods
• boolean ent.isTamed()
• boolean ent.isTameable()

• boolean writenbt(String[] nbtOperations)