Scenária

A JavaScript scene editor for Box2D with behavior programming

Table of contents

• Examples and links
• Quick glossary
• The enviroment
• World
• Entities
• Joints
• Behavior
• Value holders
• Entity filters
• Actions

Examples and links

First things first, here's a link to the newest deployed version of the editor: https://jkbmat.github.io/bakalarska-praca-dist/.

And here's some examples of Scenária in action:

• Voleyball
• Pong
• Weird Pong with dampened weld joints

Controls: WASD and arrow keys

Quick glossary

• Entity is a combination of Box2D's body, shape and fixture. Scenária doesn't support entities with multiple shapes. The workaround for this issue is to use weld joints.
• Joint holds two entities together and defines their interaction

The enviroment

Here's how the editor looks once it's freshly started:

The main sections are:

1. Workspace

• The place for entity and joint manipulation

2. Contextual sidebar

• Shows information about the currently selected object
• Can be resized

3. Entity list

• Shows a list of all existing entities, their colors and types.
• Allows for quick selection of an entity

4. Toolbar

• Contains elements controlling the enviroment
• Start/Stop button controls the running state of the simulation
• Save/Load buttons allows the user to save or load scenes to the local machine or the internet
• Remove all button removes all entities and joints from the scene
• Undo/Redo buttons step through scene history one step backwards/forwards
• Collision groups button sets which collision groups should and should not interact. More on this in section Entities.
• Tool buttons
  • Select tool is used for selecting and repositioning entities and joints
  • Rectangle and circle tools are used for creating new entities with their respective shapes
• Joint buttons are used for creating new joints. More on this in the section Joints
• Zoom slider controls the zoom level of the enviroment
• Language chooser allows changing the editor's language
  • Language files are located in the folder /app/translations/. Feel free to translate the editor to any language of your choice!

World

If no joints or entities are selected, the contextual sidebar shows information about the simulation world. Here you can set the gravity vector and camera style.

Camera can be either:

• Locked on point: Static
• Locked on entity: Always centered on an entity of your choice

Entities

To add a new entity to the simulation, simply choose the desired tool and create the entity in the work space using drag & drop. It will be assigned default attributes and a random color. Each entity is assigned a layer and a collision group. Layers determine the order in which entities are drawn. Collision groups determine which entities should interact with which other entities. The Collision groups window, accessible form the toolbar, is a place to define collision group interaction.

Collision groups 2 and 3 will now no longer interact

Aside from layer and collision group number, an entity has the following attributes:

• ID: A name, so to speak
• X/Y position
• Width/Height
• Rotation
• Fixed rotation: The entity's rotation will stay fixed
• Restitution: "Bounciness" of the entity.
• Friciton
• Density: Combined with its dimensions, density determines an entity's weight
• Precise collision checking at high velocities: Also called the bullet flag. Improves collision checking of quick moving entities, so they don't pass through thin entities. This is hovewer more computation-intense.
• Color
• Body type
  • Dynamic: The basic entity type
  • Static: Immovable entity. Has infinite mass and cannot be moved by any interactions, impulses or forces.
  • Kinematic: Same as the static body type, but can be interacted with using impulses and forces. It also has infinite mass, so interaction with static entities is ignored (Interaction of two objects with infinite mass is not defined in Newtonian physics).

Joints

Joints bind two entities together and change how they behave. To create a joint, first click on the joint's button in the toolbar. A dialog will appear in the contextual sidebar, where the connected entities need to be chosen.

After creating the joint, the following attributes can be changed:

• ID: Name of the joint. Unused as of yet.
• Connected entities should collide
• Connected entities and the relative positions of the joint

Each type of joint can also have additional attributes:

• Weld joint: Holds two entities together at fixed distance and angle
• Damping frequency: How often the entities' positions should be corrected. 0 is fixed positions, otherwise the lower, the bouncier.
• Revolute joint: The two entities rotate about a common point (imagine a hinged door).
• Rope joint: Constricts maximal distance between two entities
• Maximum rope length

Behavior

The real strength of Scenária lies in editing Entities' behaviors. The behavior editor can be accessed by clicking on Set behavior button in the contextual sidebar when an entity is selected.

The behavior system is strongly typed using the following types:

• boolean
• number
• string
• action
• entityfilter
• literal

A behavior comprises of two parts:

• One condition: (type: boolean) Is checked on every frame
• One or more actions: (type: action) If the condition is fulfilled, all of the behavior's actions are carried out.

An entity can have any number of behaviors.

The full list of implemented commands is as follows:

Value holders

Name	Type	Arguments	Description
AND	boolean	Operand A boolean Operand B boolean	Evaluates to true if both operands are true, false otherwise
OR	boolean	Operand A boolean Operand B boolean	Evaluates to true if at least one of the operands is true, false otherwise
NOT	boolean	Operand boolean	Reverses the value of the operand
true	boolean		Evaluates to true
false	boolean		Evaluates to false
text	string	Value literal	Evaluates to a string
number	number	Value literal	Evaluates to a number
randomNumber	number	Min number Max number	Evaluates to a random integer in range <min, max>
+	number	Operand A number Operand B number	Evaluates to the sum of its operands
*	number	Operand A number Operand B number	Evaluates to the product of its operands
/	number	Operand A number Operand B number	Evaluates to the quotient of its operands
-	number	Operand A number Operand B number	Evaluates to the difference of its operands
>	boolean	Operand A number Operand B number	Evaluates to true if Operand A is greater than Operand B
<	boolean	Operand A number Operand B number	Evaluates to true if Operand A is lesser than Operand B
=	boolean	Operand A number Operand B number	Evaluates to true if Operand A is equal to Operand B
getX	number	Entity entityfilter	Evaluates to x-axis position of the first entity in argument
getY	number	Entity entityfilter	Evaluates to y-axis position of the first entity in argument
velocityX	number	Entity entityfilter	Evaluates to x-axis velocity of the first entity in argument
velocityX	number	Entity entityfilter	Evaluates to y-axis velocity of the first entity in argument
getGravityX	number		Evaluates to x-axis strength of the world's gravity
getGravityY	number		Evaluates to y-axis strength of the world's gravity
isTouching	boolean	Entity filter A entityfilter Entity filter B number	Evaluates to true if any of the entities from Entity filter A are touching any of the entities from Entity filter B
countEntities	number	Entity filter entityfilter	Evaluates to the number of entities in Entity filter
isButtonDown	boolean	Keycode number	Evaluates to true if the specified button is currently pressed
isButtonUp	boolean	Keycode number	Evaluates to true if the specified button has been released

You can use keycode.info to find keycodes of buttons.

Entity filters

All entity filters are of type entityfilter. All entity filters except thisEntity, allEntities and filterById take an entityfiler as the first argument, which they then filter further.

Name	Arguments	Description
thisEntity		Contains the entity owning the behavior
allEntities		Contains all entities in the scene
filterById	ID string	Contains an entity with the specified ID
filterByGroup	Filter entityfilter Collision group number	Contains all entities from Filter that belong to the specified collision group
filterByLayer	Filter entityfilter Layer number	Contains all entities from Filter that belong to the specified layer
filterByContactWith	Filter entityfilter Entities entityfilter	Contains all entities from Filter that are touching any of the entities in Entities

Actions

Actions are executed when their behavior's condition is fulfilled. All actions are of type action.

Name	Arguments	Description
setColor	Entities entityfilter Color string	Sets the color to CSS color Color for all Entities
remove	Entities entityfilter	Removes all Entities
setGravity	X number Y number	Sets the world's gravity
setPosition	Entities entityfilter X number Y number	Sets the position for all Entities
setAngularVelocity	Entities entityfilter Strength number	Sets the angular velocity for all Entities
setLinearVelocity	Entities entityfilter X number Y number	Sets the linear velocity for all Entities
applyTorque	Entities entityfilter Strength number	Applies angular force to all Entities
applyLinearForce	Entities entityfilter X strength number Y strength number	Applies a linear force to all entities
applyAngularImpulse	Entities entityfilter Strength number	Applies an angular impulse to all entities
applyLinearImpulse	Entities entityfilter X strength number Y strength number	Applies a linear impulse to all entities