JsBattle Docs

JsBattle Engine API

Classes

AiDefinition

Describes AI algorithm of the tank. There could be two sources of AI scripts: files or string variable. Depending on source of scripts fromFile() or fromCode() methods should be used to initialize the object

Renderer

Renders simulation of the battle. The object must be passed to constructor of Simulation object

Simulation

Battle simulation component. Process the simulation updating all related objects and refreshing the renderer.

Tank

Object represents a tank that is involved in the battle during simulation

AiDefinition

Describes AI algorithm of the tank. There could be two sources of AI scripts:
files or string variable. Depending on source of scripts fromFile() or fromCode()
methods should be used to initialize the object

Kind: global class

new AiDefinition()

Creates AiDefinition. Constructor is not available outside of
JsBattle.min.js library. To create AiDefinition object use
JsBattle.createAiDefinition() instead

aiDefinition.name ⇒

Kind: instance property of AiDefinition
Returns: name of the AI. The same name will be assigned to the tank

aiDefinition.teamName ⇒

Kind: instance property of AiDefinition
Returns: name of the team

aiDefinition.executionLimit ⇒

Kind: instance property of AiDefinition
Returns: Maximum time for execution of AI script (in milliseconds)

aiDefinition.executionLimit

Kind: instance property of AiDefinition

Param Type Description
limit Number Maximum time for execution of AI script (in milliseconds)

aiDefinition.filePath ⇒

Kind: instance property of AiDefinition
Returns: path to file with code of Web Worker where the AI will be ran.

aiDefinition.code ⇒

Kind: instance property of AiDefinition
Returns: source code of AI algorithm as a string. This property is not empty only for AIs created by fromCode() call
See: AiDefinition.fromCode()

aiDefinition.initData ⇒

Kind: instance property of AiDefinition
Returns: optional initial data that is passed to the AI and can be accessed from tank info object (info.initData)

aiDefinition.useSandbox ⇒

Kind: instance property of AiDefinition
Returns: true if AI should be sandboxed. Otherwise false. By default, all AIs are sandboxed.

aiDefinition.toJSON() ⇒

Kind: instance method of AiDefinition
Returns: JSON representation of AiDefiniton

aiDefinition.fromJSON(data)

Kind: instance method of AiDefinition

Param Type Description
data object JSON data to be parsed

aiDefinition.clone() ⇒

Kind: instance method of AiDefinition
Returns: copy of the object

aiDefinition.fromFile(tankName, initData)

Creates AI definition that has source codes in a file. All AI scripts
are kept in /tanks/[tankName].tank.js files

Kind: instance method of AiDefinition

Param Type Description
tankName String name of the tank. Its source code is kept in /tanks/[tankName].tank.js
initData object optional initial data that is passed to the AI and can be accessed from tank info object (info.initData)

aiDefinition.fromCode(tankName, code, initData)

Creates AI definition that has the algorithm codded in provided in string parameter.

Kind: instance method of AiDefinition

Param Type Description
tankName String name of the tank.
code String JavaScript code of AI script.
initData object optional initial data that is passed to the AI and can be accessed from tank info object (info.initData)

aiDefinition.assignToTeam(name)

Set name of the team. Tanks from the same team can coomunicate with eachother and cooperate

Kind: instance method of AiDefinition

Param Type Description
name string unique name of the team

aiDefinition.disableSandbox()

Allows to running code of AI in the same sandbox as the core of JsBattle game. It is
potentially dangerous since code of AI Script can access code of JS Battle and
influence it. However disabling sandbox can significantly increase performance
(especially if you run several simulations in concurrent). Use this approach
only for trusted AI code.

Kind: instance method of AiDefinition

Renderer

Renders simulation of the battle. The object must be passed to
constructor of Simulation object

Kind: global class
See: Simulation

renderer.quality ⇒

Kind: instance property of Renderer
Returns: value from 0 to 1 that represents the current quality of the renderer. This parameter is controlled by Simulation object
See: Simulation.setRendererQuality()

renderer.initBatlefield(battlefield)

Renders the battlefield. Called only at the beginning. Used usually to render
background of the Simulation

Kind: instance method of Renderer

Param Type Description
battlefield Battlefield battlefield object

renderer.preRender()

Called before rendering of each frame

Kind: instance method of Renderer

renderer.postRender()

Called after rendering of each frame

Kind: instance method of Renderer

renderer.renderTank(tank, events)

Render a tank

Kind: instance method of Renderer

Param Type Description
tank Tank a tank to be rendered
events Array list of events related to the tank that occurred since the last call of this method

renderer.renderClock(msElapsed, msLimit)

Renders clock of the battle

Kind: instance method of Renderer

Param Type Description
msElapsed Number time that has elapsed (in milliseconds)
msLimit Number maximum battle duration (in milliseconds)

renderer.renderTankStats(tankList)

Renders statistics of all tanks. Called once per frame

Kind: instance method of Renderer

Param Type Description
tankList Array list of all tanks that are involved in the battle

renderer.renderBullet(bullet, events)

Render a bullet

Kind: instance method of Renderer

Param Type Description
bullet Bullet a bullet to be rendered
events Array list of events related to the bullet that occurred since the last call of this method

renderer.setSpeed()

Sets speed of the simulation. Could be used to time-scale animations so they match simulation speed

Kind: instance method of Renderer
Pram: Number multiplier - simulation speed multiplier

renderer.stop()

Stops renderinf loop of the battle. After this call, renderinig cannot be resumed.

Kind: instance method of Renderer

renderer.dispose()

Clean up and remove all resources used by renderer

Kind: instance method of Renderer

Simulation

Battle simulation component. Process the simulation updating all related objects
and refreshing the renderer.

Kind: global class

new Simulation(renderer, debug)

Create Simulation object. Constructor is not available outside of
JsBattle.min.js library. To create Simulation object use
JsBattle.createSimulation(renderer) instead

Param Type Description
renderer Renderer Renderer used to present results of the simulation
debug Boolean turn on logging on the console

simulation.tankList ⇒

Kind: instance property of Simulation
Returns: all tanks that were added to the battle

simulation.teamList ⇒

Kind: instance property of Simulation
Returns: list of teams

simulation.renderer ⇒

Kind: instance property of Simulation
Returns: renderer attached to the simulation

simulation.timeElapsed ⇒

Kind: instance property of Simulation
Returns: amount of time that has elapsed from the beginning of the battle (in milliseconds)

simulation.timeLimit ⇒

Kind: instance property of Simulation
Returns: maximum duration of the battle (in milliseconds). The battle will be over after that time.

simulation.setRngSeed(seed)

Seed random number generator. Each time when you seed rng with the same data
it will return the same sequence of numbers. That feature can be used
to reconstruct exactly the same, "randomized" simulation condidtions.

IMPORTANT! set it just after calling constructor of the calss. Otherwise
some RNG calls could be unseeded.

Kind: instance method of Simulation

Param Type Description
seed Number rng seed data

simulation.getRngSeed() ⇒

Kind: instance method of Simulation
Returns: seed of random number generator

simulation.getRandom() ⇒

Kind: instance method of Simulation
Returns: random number from seeded rng

simulation.log(msg)

log message if logging is enabled

Kind: instance method of Simulation

Param Type Description
msg string message to log

simulation.setFinishCondition(callback)

set custom condition of battle finish. Once provided callbacl return true, the simulation will be over

Kind: instance method of Simulation

Param Type Description
callback function callback determining end of the battle. It takes one argument (simulation object) and return true (stop simulation) or false (continue simulation)

simulation.init(width, height)

Initialize the battle field. Must be called before any other calls
to simulation object

Kind: instance method of Simulation

Param Type Description
width Number width of the battlefield
height Number height of the battlefield

simulation.start()

Starts simulation of the battle. It will initialize all AI scripts, trigger onStart event
and launch rendering and simulation processing loops. Remember to call Simulation.init() and
Simulation.addTank() before executing this method.

Kind: instance method of Simulation
See: Simulation.onStart()

simulation.addTank(aiDefinition)

Create a tank according to provided AiDefinition. Remember to add at
least two tanks to the battle. Otherwise, it will stop immediately and
the winner will be recognized

Kind: instance method of Simulation

Param Type Description
aiDefinition AiDefinition defintion of tank AI script

simulation.setSpeed(multiplier)

Set speed multiplier of the simulation. Setting to 2means that everything will be
two times faster than usual. Setting to 0.5 will simulate the battle 2 times slower
than usual

Kind: instance method of Simulation

Param Type Description
multiplier Number simulation speed multiplier

simulation.setRendererQuality(qualityLevel)

Sets quality of renderer controlled by simulation object.
You can specify a value between 0 (lowest quality) and 1 (highest quality)
or allow the simulation to adjust it automatically by passing 'auto' string
Automatic quality adjustment try to keep the speed of the animation at proper level.
If simulation is lagging, quality will be reduced to ensure that the simulation
does not take longer than it should

Kind: instance method of Simulation

Param Type Description
qualityLevel Number | String number between 0 and 1 or 'auto' string

simulation.stop()

Stops battle simulation. It also stops rendering loop.
After calling this method you should not try to call
start to resume the battle but rather create a new
Simulation object and initialize it from the beginning

Kind: instance method of Simulation

simulation.onStep(callback)

Allow adding a callback that will be called after each step of simulation
processing loop. The callback takes no arguments. The frequency of this event
depends on simulation speed.

Kind: instance method of Simulation
See: Simulation.setSpeed()

Param Type Description
callback function callback that will be called on each event occurence.

simulation.onRender(callback)

Allow adding a callback that will be called after each refresh of the renderer.
The callback takes no arguments. onRender and onStep event are not synchronized
and may be called at different intervals. Increasing of animation speed will not
increase rendering frequency. Rendering frequency is affected by quality of
rendering parameter

Kind: instance method of Simulation
See

Param Type Description
callback function callback that will be called on each event occurence.

simulation.onStart(callback)

Allow adding a callback that will be called when the battle is started.
It is executed after initialization of all AI Scripts, just before
first step of simulation processing loop. The callback takes no arguments.

Kind: instance method of Simulation

Param Type Description
callback function callback that will be called on each event occurence.

simulation.onFinish(callback)

Allow adding a callback that will be called when the battle is over.
The callback takes no arguments.

Kind: instance method of Simulation

Param Type Description
callback function callback that will be called on each event occurence.

simulation.onError(callback)

Allow adding a callback that will be called when an error occur.
The callback takes one arguments: error message

Kind: instance method of Simulation

Param Type Description
callback function callback that will be called on each event occurence.

simulation.createUltimateBattleDescriptor() ⇒

Create Ultimate Battle Descriptor that contains all data requied to replay
the battle and reflect its exact course.

Kind: instance method of Simulation
Returns: UltimateBattleDescriptor object

simulation.hasTeams() ⇒

Kind: instance method of Simulation
Returns: true if at least two tanks are cooperating within one team

Tank

Object represents a tank that is involved in the battle during simulation

Kind: global class

new Tank(aiDefinition, id, team)

Constructor should not be called directly but through
Simulation.addTank() method

Param Type Description
aiDefinition AiDefinition definition of tank's AI Script
id Number unique id of the tank
team Team reference to team object where the tank belongs

tank.id ⇒

Kind: instance property of Tank
Returns: unique id of the tank

tank.skin ⇒

Kind: instance property of Tank
Returns: skin name applied to the tank

tank.state ⇒

Kind: instance property of Tank
Returns: an object that represents current state of the tank

tank.energy ⇒

Kind: instance property of Tank
Returns: amount of energy that the tank has

tank.score ⇒

Kind: instance property of Tank
Returns: current score of the tank

tank.maxEnergy ⇒

Kind: instance property of Tank
Returns: initial amount of the energy

tank.radarRange ⇒

Kind: instance property of Tank
Returns: range of tank's radar

tank.radarFocal ⇒

Kind: instance property of Tank
Returns: angle that radar field covers

tank.name ⇒

Kind: instance property of Tank
Returns: name of the tank

tank.fullName ⇒

Kind: instance property of Tank
Returns: full name contains name of the tank and its unique ID

tank.team ⇒

Kind: instance property of Tank
Returns: name of the team

tank.x ⇒

Kind: instance property of Tank
Returns: x position of the tank

tank.y ⇒

Kind: instance property of Tank
Returns: y position of the tank

tank.speed ⇒

Kind: instance property of Tank
Returns: linear speed of the tank

tank.angle ⇒

Kind: instance property of Tank
Returns: rotation of tank's body

tank.throttle ⇒

Kind: instance property of Tank
Returns: current throttle of the tank

tank.hasBoost ⇒

Kind: instance property of Tank
Returns: true if tank has boost turned on. Otherwise false

tank.boost ⇒

Kind: instance property of Tank
Returns: amount of boost that has left

tank.maxBoost ⇒

Kind: instance property of Tank
Returns: initial amount of boost

tank.gunAngle ⇒

Kind: instance property of Tank
Returns: rotation of tank's gun (relative to tank's body)

tank.radarAngle ⇒

Kind: instance property of Tank
Returns: rotation of tank's radar (relative to tank's body)

tank.targetingAlarm ⇒

Kind: instance property of Tank
Returns: true if tank is on the radar of an enemy. Otherwise false

tank.debugData ⇒

Kind: instance property of Tank
Returns: debug data set by AI script via control.DEBUG