Map effects

A map effect is one piece of behaviour attached to a map: a light, a looping sound, a plane flying over, the time of day. Effects are how a map gets its atmosphere, and they also hold settings such as the map’s name and teams.

Each effect is a JSON object, and effectType picks the kind:

{
  "effectType": "positioned_looping_sound",
  "position": { "x": 4248.25, "y": 13.5, "z": 3233.5 },
  "sound": "bf:ambient.lsp.vehicle.truck.engine.idle",
  "volume": 1.0,
  "pitch": 0.8,
  "activationDistance": 32.0
}

In game, the Creator Wand places effects, the Editor Wand changes their fields and the Rotation Wand turns them.

Where effects go

Effects are declared in three places.

On the map. The mapEffects list at the top of a map asset holds the four map settings and nothing else. Other effects do nothing here.

On an environment. Each environment has its own mapEffects list, and everything else goes here. Only the environment being played runs, so day and night versions of a map can look and sound different.

Through a template. An environment’s mapEffectTemplates list places a template, which saves repeating the same effect:

{
  "template": "tmp_positioned_particle_far_smoke",
  "overrides": {
    "position": { "x": -69.5, "y": 17.5, "z": -46.5 },
    "effectId": "village_smoke",
    "defaultOn": false
  }
}

The position here is an anchor, added to the template’s own position. Other keys replace the matching fields of the template’s effect. An effect placed this way gets a generated uuid, so setting one in overrides has no effect.

Fields every effect has

Field	Type	Default	Meaning
effectType	Text	Required	The kind of effect.
uuid	UUID	Random	Identifies the effect. Set one if a link needs to find it, as a missing uuid is new on every load.
effectId	Text	None	A name for scripts and trigger conditions. Several effects can share one.
position	Position	0, 0, 0	Where the effect is in the world.
defaultEnabled	Boolean	true	Whether the effect runs on players’ games at the start of a match.
link	Object	None	Attaches the effect to a moving source. See Links.

Value types

Type	Format
Position	{ "x": 1.0, "y": 2.0, "z": 3.0 }
Area corner	{ "x": 1.0, "y": 2.0 }, where y is the world Z coordinate.
Block position	[1, 2, 3]
Colour	A whole number, or hex text such as "#FFE8B0".
Integer colour	A whole number only, such as 16777215 for white.
Resource	A namespaced id, such as bf:ambient.loop.wind.
Ticks	Game ticks. There are 20 in a second.

Switching effects from a script

Some effects can be switched on and off by a mission script. They take a defaultOn field, which sets their state at the start of a mission, and an effectId to address them by:

effects.on("battle_planes")
effects.off("lz_searchlight_2", "lz_tracer_1")

Every effect with that effectId is switched, and the script stops with an error if none can be. Restarting the mission puts them all back to defaultOn. See effects.

These effects can be switched: fly_by, pathed_vehicle_entities, positioned_bombing_flash, positioned_bullet_tracer, positioned_light_source, positioned_particle, positioned_spot_light_source, positioned_sprite, searchlight and watchlight.

effects.waitDone(id) waits for a pathed_vehicle_entities effect to finish its route.

defaultOn and defaultEnabled are separate. Scripts use defaultOn, while defaultEnabled is for trigger conditions.

Links

A link attaches an effect to a moving vehicle, so headlights can follow a truck. Any effect can be linked. The source must be a pathed_vehicle_entities or positioned_vehicle effect in the same environment, found by its uuid.

"link": {
  "source": "d2f7a4c1-8b3e-4e69-9a51-6c0f2e7b3d48",
  "offset": { "x": 0.5, "y": 1.0, "z": 2.75 },
  "pitch": 6.0
}

Field	Type	Default	Meaning
source	UUID	Required	The uuid of the effect to follow.
offset	Position	0, 0, 0	The offset from the source, where x is right, y is up and z is forward.
yaw	Number	0	Degrees to turn from the source’s heading. Positive turns right.
pitch	Number	0	Degrees to tilt. Positive tilts down.
followSwitch	Boolean	true	Whether a switchable effect copies its source’s on or off state.

While linked, the effect’s own position is ignored. yaw and pitch apply to effects that can turn: positioned_area_light_source, positioned_artillery_gun, positioned_bombing_flash, positioned_spot_light_source and positioned_vehicle.

Map settings

These go in the map’s own mapEffects list. Without them, the map falls back to default values.

map_name

The map’s display name.

Field	Type	Default	Meaning
mapName	Text	Required	The name shown to players.

author

The map’s author.

Field	Type	Default	Meaning
author	Text	Required	The author shown to players.

teams

The two teams on the map.

Field	Type	Default	Meaning
alliesTeam	Resource	Required	The Allied team, such as bf:gb_parachute.
axisTeam	Resource	Required	The Axis team, such as bf:ger_wehrmacht.

music_set

The map’s music. The only set at present is europe, which is also the default.

Field	Type	Default	Meaning
musicSet	Text	Required	The name of the music set.

Environment settings

time

Fixes the time of day.

Field	Type	Default	Meaning
time	Whole number	Required	The time of day in ticks. 18000 is midnight.

shader

Applies a post-process shader to the screen.

Field	Type	Default	Meaning
shader	Resource	None	The shader, such as bf:shaders/post/battlefield.json.

sky_settings

Hides the sky or clouds.

Field	Type	Default	Meaning
disableSky	Boolean	false	Hides the sky.
disableClouds	Boolean	false	Hides the clouds.

water_color

Sets the colour of water.

Field	Type	Default	Meaning
color	Integer colour	White	The water colour.

weather

Runs a weighted list of weather states. When one ends, the game picks the next and fades across to it.

Field	Type	Default	Meaning
entries	List	Empty	The weather states.
transitionTicks	Whole number	200	How long each fade lasts, in ticks.

Each entry takes these fields:

Field	Type	Default	Meaning
weight	Number	1.0	How likely this entry is, relative to the others.
minDurationTicks	Whole number	1200	The shortest time it lasts.
maxDurationTicks	Whole number	2400	The longest time it lasts.
interiorSound	Resource	None	Ambience while indoors.
exteriorSound	Resource	None	Ambience while outdoors.
playerInteriorSound	Resource	None	A further ambience sound while indoors.
playerExteriorSound	Resource	None	A further ambience sound while outdoors.
hasFogColor	Boolean	false	Turns on fogColor.
fogColor	Colour	White	The fog colour.
hasFogDensity	Boolean	false	Turns on the two fog densities.
nearFogDensity	Number	0	The near fog density.
farFogDensity	Number	0	The far fog density.
hasSkyColor	Boolean	false	Turns on skyColor.
skyColor	Colour	White	The sky colour.
hasLightColor	Boolean	false	Turns on lightColor.
lightColor	Colour	White	The light colour.
ambientSounds	List	Empty	One-off sounds, described below.
fx	Object	None	Visual effects, described below.

An ambientSounds entry plays a random sound from a group:

Field	Type	Default	Meaning
tickIntervalMin	Whole number	Required	The shortest gap between sounds.
tickIntervalMax	Whole number	Required	The longest gap between sounds.
soundGroup	Resource	None	The sound group, such as bf:collection_town.
playbackEnvironment	Text	ANY	Where it plays: ANY, INTERIOR or EXTERIOR.

The fx object takes these fields:

Field	Type	Default	Meaning
weatherType	List of text	Empty	Any of snow, light_snow, heavy_snow, falling_leaves, rainstorm, sandstorm, sandy_floor and snowy_floor.
clouds	List	None	Cloud layers, drawn back to front.
darkness	Number	None	Darkness applied to the world.
botViewDistance	Number	None	How far bots can see, in blocks.
hideSniperGlint	Boolean	false	Hides the glint on sniper scopes.
interiorHeightmap	Object	None	Camera sway while indoors.
exteriorHeightmap	Object	None	Camera sway while outdoors.

A cloud layer takes these fields:

Field	Type	Default	Meaning
texture	Resource	Required	A tileable 256 by 256 cloud texture.
yOffset	Number	0	Blocks added to the normal cloud height.
speedMultiplier	Number	1.0	Multiplies the drift speed.
scale	Number	1.0	The size of the cloud pattern.
color	Colour	White	The tint.
alpha	Number	1.0	Multiplies the opacity.

A camera sway object has x, y and z lists. Each list entry is a wave with frequency, amplitude and an optional phaseShift in radians, and larger frequency values are slower.

{
  "effectType": "weather",
  "transitionTicks": 600,
  "entries": [
    {
      "weight": 0.5,
      "exteriorSound": "bf:ambient.loop.wind",
      "interiorSound": "bf:ambient.loop.interior.house",
      "hasFogDensity": true,
      "farFogDensity": 200.0,
      "ambientSounds": [
        { "tickIntervalMin": 60, "tickIntervalMax": 120, "soundGroup": "bf:collection_town" }
      ],
      "fx": {
        "weatherType": ["falling_leaves"],
        "clouds": [
          { "texture": "bf:textures/environment/clouds0.png", "yOffset": -20.0, "speedMultiplier": 3.0 }
        ]
      }
    }
  ]
}

Sound

positioned_looping_sound

Loops a sound at its position.

Field	Type	Default	Meaning
sound	Resource	None	The sound.
volume	Number	Required	The volume.
pitch	Number	Required	The pitch.
activationDistance	Number	Required	Players within this many blocks hear it.

positioned_timed_sound

Plays a sound at its position on a timer.

Field	Type	Default	Meaning
sound	Resource	None	The sound.
maxTime	Whole number	Required	Ticks between plays.
volume	Number	Required	The volume.
pitch	Number	Required	The pitch.
activationDistance	Number	Required	Players within this many blocks hear it.

Lights

The application field on lights is default, or fire_flicker to make the light flicker. inscattering adds a visible glow in the air, and 0 turns it off.

positioned_light_source

A point light. Switchable.

Field	Type	Default	Meaning
color	Integer colour	Required	The light colour.
brightness	Number	Required	The brightness.
radius	Number	Required	The radius in blocks.
occlude	Boolean	Required	Whether blocks stop the light.
inscattering	Number	0	The strength of the glow.
application	Text	default	The brightness animation.
defaultOn	Boolean	true	Whether it starts on.

{
  "effectType": "positioned_light_source",
  "position": { "x": -53.0, "y": 13.75, "z": 22.25 },
  "effectId": "village_light_1",
  "color": 16772822,
  "brightness": 3.0,
  "radius": 16.0,
  "occlude": false,
  "defaultOn": false
}

positioned_spot_light_source

A cone of light that can be aimed. Switchable.

Field	Type	Default	Meaning
color	Colour	Required	The light colour.
brightness	Number	Required	The brightness.
size	Number	Required	The spread of the cone, in degrees.
angle	Number	Required	The maximum light angle from the surface, in degrees.
distance	Number	Required	How far the light reaches, in blocks.
occlude	Boolean	Required	Whether blocks stop the light.
inscattering	Number	0	The strength of the glow.
rotation_x	Number	0	Rotation about X, in degrees.
rotation_y	Number	0	Rotation about Y, in degrees.
rotation_z	Number	0	Rotation about Z, in degrees.
application	Text	default	The brightness animation.
defaultOn	Boolean	true	Whether it starts on.

positioned_area_light_source

A rectangular panel of light.

Field	Type	Default	Meaning
color	Colour	Required	The light colour.
brightness	Number	Required	The brightness.
size_x	Number	Required	The width in blocks.
size_y	Number	Required	The height in blocks.
angle	Number	Required	The cone half-angle, in degrees.
distance	Number	Required	How far the light reaches, in blocks.
occlude	Boolean	Required	Whether blocks stop the light.
inscattering	Number	0	The strength of the glow.
rotation_x	Number	0	Rotation about X, in degrees.
rotation_y	Number	0	Rotation about Y, in degrees.
rotation_z	Number	0	Rotation about Z, in degrees.
application	Text	default	The brightness animation.

searchlight

A beam that pans between points and can catch players. Switchable. When a player is caught, a mission script receives the event searchlight, caught with the player’s name.

Field	Type	Default	Meaning
sweep	List	Empty	The points the beam pans through, each { "yaw": 0, "pitch": 0 }.
sweepTicks	Whole number	400	Ticks for one full pass across all points.
color	Colour	White	The light colour.
brightness	Number	6.0	The brightness.
size	Number	7.0	The half-angle of the beam, in degrees. It’s also the detection cone.
angle	Number	30.0	The maximum light angle from the surface, in degrees.
distance	Number	80.0	How far the beam reaches, in blocks.
occlude	Boolean	false	Whether blocks stop the light.
inscattering	Number	1.5	The strength of the glow.
detect	Boolean	true	Whether the beam catches players. Turn it off for background lights.
detectionTarget	Text	body	The part of the player the beam must reach: body or eyes.
graceTicks	Whole number	10	Ticks a player must stay in the beam before being caught.
defaultOn	Boolean	true	Whether it starts on.

watchlight

A sweeping beam of light for the background. Switchable.

Field	Type	Default	Meaning
heightOffset	Number	61.0	The height offset of the beam, in blocks.
imageScale	Number	6.0	The scale of the beam image.
maxRotation	Number	35.0	How far the beam turns, in degrees.
defaultOn	Boolean	true	Whether it starts on.

positioned_sprite

A flat image that always faces the player, such as a lens flare. It fades when its visibility changes. Switchable.

Field	Type	Default	Meaning
texture	Resource	bf:textures/misc/world/sprite_flare.png	The image.
size	Whole number	32	The size. 32 is about two-thirds of a block on screen.
alpha	Number	1.0	The opacity.
color	Colour	White	The tint.
hasDepth	Boolean	false	Whether blocks can cover it.
onlyRenderIfInView	Boolean	false	Shows it only while the player has a clear line to it.
defaultOn	Boolean	true	Whether it starts on.

Battle ambience

positioned_bombing_flash

A flash in the distance, for a far-off battle. Switchable.

Field	Type	Default	Meaning
rotation	Number	Required	The direction it faces, in degrees.
color	Integer colour	Required	The flash colour.
scale	Number	Required	The size of the flash.
sound	Resource	Required	The sound played with each flash.
defaultOn	Boolean	true	Whether it starts on.

positioned_bullet_tracer

Fires harmless tracers from its position toward a destination. Switchable.

Field	Type	Default	Meaning
endPos	Position	Required	Where the tracers go.
chance	Number	Required	The chance of a tracer each tick.
playSound	Boolean	Required	Whether a tracer makes a sound.
spread	Position	Required	The random spread at the destination, in blocks per axis.
defaultOn	Boolean	true	Whether it starts on.

positioned_rocket

Fires a rocket from its position at regular intervals.

Field	Type	Default	Meaning
interval	Whole number	Required	Ticks between rockets.
pitch	Number	Required	The aim pitch, in degrees.
yaw	Number	Required	The aim yaw, in degrees.
pitchWidth	Number	Required	The random deviation in pitch, in degrees.
yawWidth	Number	Required	The random deviation in yaw, in degrees.

positioned_rocket_barrage

Fires a group of rockets from its position at regular intervals.

Field	Type	Default	Meaning
interval	Whole number	Required	Ticks between each group of rockets.
amount	Whole number	Required	The number of rockets in each group.
fireRate	Whole number	Required	Ticks between each rocket in a group.
pitch	Number	Required	The aim pitch, in degrees.
yaw	Number	Required	The aim yaw, in degrees.
pitchWidth	Number	Required	The random deviation in pitch, in degrees.
yawWidth	Number	Required	The random deviation in yaw, in degrees.
fireSound	Resource	None	The sound of each rocket firing.

positioned_artillery_gun

An artillery gun that turns between random targets and fires.

Field	Type	Default	Meaning
rotation	Number	Required	The starting direction, in degrees.
maxYaw	Whole number	Required	How far it can turn from there, in degrees.
blockType	Resource	Optional	The gun model, such as bf:150mm_tbtsk_c36_gun.
animation	Text	None	An animation to play on the gun.
commanderSound	Resource	None	A callout played before firing.

falling_artillery

Drops artillery shells from the sky at random spots in an area.

Field	Type	Default	Meaning
startPos	Area corner	Required	One corner of the area.
endPos	Area corner	Required	The opposite corner.
artilleryTimeMax	Whole number	600	The longest gap between shells, in ticks.

random_explosion

Sets off explosions on the ground at random spots in an area.

Field	Type	Default	Meaning
startPos	Area corner	Required	One corner of the area.
endPos	Area corner	Required	The opposite corner.
explodeTimeMax	Whole number	200	The longest gap between explosions, in ticks.

lightning

Strikes lightning at random spots in an area, with thunder and a flash.

Field	Type	Default	Meaning
startPos	Area corner	Required	One corner of the area.
endPos	Area corner	Required	The opposite corner.
lightningTimeMax	Whole number	2400	The longest gap between strikes, in ticks.

Aircraft and vehicles

fly_by

Flies planes built from blocks from a spawn area to a target area. Switchable.

Field	Type	Default	Meaning
spawnInterval	Whole number	Required	Ticks between spawns.
speed	Number	Required	The speed in blocks per tick.
min0	Position	Required	The first corner of the spawn area.
min1	Position	Required	The second corner of the spawn area.
max0	Position	Required	The first corner of the target area.
max1	Position	Required	The second corner of the target area.
blocks	List of resources	Required	The plane blocks to pick from, such as bf:black_plane.
maxPlanesPerSpawn	Whole number	2	The most planes spawned at once.
soundEvent	Resource	None	The sound of a plane passing.
soundDistanceMin	Whole number	-1	The distance in blocks at which a plane plays its sound. -1 works it out from the speed.
defaultOn	Boolean	true	Whether it starts on.

{
  "effectType": "fly_by",
  "position": { "x": -6.0, "y": 42.0, "z": -8.0 },
  "effectId": "battle_planes",
  "spawnInterval": 200,
  "speed": 5.0,
  "min0": { "x": 500.0, "y": 150.0, "z": 260.0 },
  "min1": { "x": 500.0, "y": 120.0, "z": -280.0 },
  "max0": { "x": -500.0, "y": 120.0, "z": 260.0 },
  "max1": { "x": -500.0, "y": 150.0, "z": -280.0 },
  "blocks": ["bf:black_plane"],
  "soundEvent": "bf:match.mapeffect.plane.flyby",
  "defaultOn": false
}

fly_by_entities

Flies vehicle planes from a spawn area to a target area.

Field	Type	Default	Meaning
spawnInterval	Whole number	Required	Ticks between spawns.
speed	Number	Required	The speed in blocks per tick.
min0	Position	Required	The first corner of the spawn area.
min1	Position	Required	The second corner of the spawn area.
max0	Position	Required	The first corner of the target area.
max1	Position	Required	The second corner of the target area.
planes	List	Required	The planes to pick from. Each needs a blockEntity and a block, both the same id, such as bf:reggiane_re2005.
soundEvent	Resource	None	The sound of a plane passing.
soundDistanceMin	Number	128	The distance in blocks at which a plane plays its sound.

sky_planes

Draws groups of planes flying in the sky.

Field	Type	Default	Meaning
radius	Whole number	Required	The distance between groups, in blocks.
repeat	Whole number	Required	The number of groups.
block	Resource	Required	The plane block, such as bf:black_plane.

pathed_vehicle_entities

Drives a vehicle along a route, with an engine sound that follows it. Switchable. With defaultOn set to false, it waits on the first point until a script switches it on. Other effects can link to it.

Field	Type	Default	Meaning
movablePath	Object	Required	The route, described below.
pauseWhenComplete	Boolean	Required	Parks on the last point instead of going back to the first.
soundVolume	Number	Required	The volume of its sounds.
blockType	Resource	Optional	The vehicle, such as bf:opel_blitz.
animation	Text	None	An animation to play on the vehicle.
animationOnFinish	Text	None	An animation to play when the route ends.
sound	Resource	None	The engine loop while driving.
soundPaused	Resource	None	The loop while paused.
soundOnStart	Resource	None	A sound that sets off with the vehicle and follows it.
soundOnFinish	Resource	None	A sound played once when it comes to rest.
defaultOn	Boolean	true	Whether it starts driving straight away.
hideWhenOff	Boolean	false	Hides the vehicle while it’s switched off.

The movablePath object takes these fields, all required:

Field	Type	Meaning
positions	List of positions	The points of the route.
speed	Number	The speed in blocks per tick.
startTime	Whole number	The wait at the start, in ticks.
finishTime	Whole number	The wait at the end, in ticks.
reverseOnEnd	Boolean	Whether it reverses back along the route at the end.

{
  "effectType": "pathed_vehicle_entities",
  "uuid": "6f2b9d4c-81e7-4a05-b3c9-d7e1f5a2c480",
  "position": { "x": -87.5, "y": 14.0, "z": 71.5 },
  "blockType": "bf:opel_blitz",
  "soundOnStart": "bf:match.gamemode.camp.mission_pathfinder.truck_pass",
  "soundVolume": 8.0,
  "pauseWhenComplete": true,
  "defaultOn": false,
  "hideWhenOff": true,
  "movablePath": {
    "speed": 0.35,
    "startTime": 0,
    "finishTime": 0,
    "reverseOnEnd": false,
    "positions": [
      { "x": -87.5, "y": 14.0, "z": 71.5 },
      { "x": -22.5, "y": 14.0, "z": 76.5 },
      { "x": -9.4, "y": 14.0, "z": 70.5 }
    ]
  }
}

positioned_vehicle

A stationary vehicle. Other effects can link to it.

Field	Type	Default	Meaning
rotation	Number	Required	The direction it faces, in degrees.
blockType	Resource	Optional	The vehicle, such as bf:ju52.
animation	Text	None	Animations to play, separated by commas. The last one loops.
texture	Resource	None	A texture to use in place of the normal one.
bypassCulling	Boolean	false	Keeps it drawn when it would normally be skipped.

World details

positioned_particle

Spawns particles around its position on a timer, such as smoke. Switchable.

Field	Type	Default	Meaning
particleType	Resource	Required	The particle, such as bf:far_smoke_particle.
maxTick	Whole number	Required	Ticks between spawns.
soundVolume	Number	Required	The volume of sound.
sound	Resource	None	A sound played with each spawn.
spreadXZ	Number	2.0	The horizontal spread, in blocks.
spreadY	Number	0	The vertical spread, in blocks.
activationDistance	Number	512.0	It only runs for players within this many blocks.
defaultOn	Boolean	true	Whether it starts on.

positioned_entity

Spawns entities at its position once per match, such as animals.

Field	Type	Default	Meaning
entity	Resource	Required	The entity, such as minecraft:chicken.
count	Whole number	Required	How many to spawn.
leashPosition	Block position	None	A fence to leash them to.

mist

Draws a layer of mist around the player at a fixed height.

Field	Type	Default	Meaning
yPos	Whole number	Required	The height of the mist.
radius	Whole number	Required	The radius in blocks.

surrender_paper

Spawns falling surrender leaflets at set positions.

Field	Type	Default	Meaning
positions	List of positions	Required	Where the leaflets appear.

Logic

trigger_condition

Turns another effect on and off when something happens in the game. On Crete, it holds back a plane crash until the match starts.

Field	Type	Default	Meaning
targetEffectId	Text	Empty	The effectId or uuid of the effect to control.
condition	Text	GAME_STARTED	The condition. GAME_STARTED is the only one, and it holds while the match is being played.

The target is on while the condition holds and off otherwise. Give the target "defaultEnabled": false so it starts off, and leave the trigger itself enabled, or it won’t run. This only affects what players see and hear, not anything the server does.

{
  "effectType": "trigger_condition",
  "position": { "x": 5208.5, "y": 39.5, "z": -1851.5 },
  "targetEffectId": "6d3ab578-9eb5-42ad-a42e-26423551a8aa"
}