Enabling Physics Support

Config.json

To enable physics, you must create a ‘sim’ directory and place a config.json file there, with the following JSON information:

{
  "websim": {
    "robot": {
      "w": 2,
      "h": 3,
      "starting_x": 2,
      "starting_y": 20,
      "starting_angle": 0
    }
  }
}

Values without units will default to feet and degrees, but you can optionally add units to your JSON:

{
  "websim": {
    "robot": {
      "w": ".66m",
      "h": "1m",
      "starting_x": "24in",
      "starting_y": "20ft",
      "starting_angle": "0rad"
    }
  }
}

Physics.js

class UserPhysics(Matter, engine, canvas, config)

You must create a physics.js file in your ‘sim’ directory and create a MyUserPhysics class that extends UserPhysics. The UserPhysics class has several methods you can override to customize your simulation:

class MyUserPhysics extends UserPhysics {
  ...
  ...
  ...
}

Note

Do NOT call the constructor function yourself. This is automatically called by the websim. If you need to do any custom initialization override the init function.

UserPhysics.addDeviceGyroChannel(angleKey)

Call this in the init function if you need to add a non-analog gyro device to the hal data.

Arguments:

• angleKey (String) – The name of the angle key in halData.robot

UserPhysics.createField(fieldConfig)

Override this function if you want to create a custom field. By default it creates a rectangular field using the dimensions provided in the config.json file.

Arguments:

• fieldConfig (Object) – The config JSON from the config.json file.

UserPhysics.createRobot(robotConfig)

Override this function if you want to create a custom robot. By default it creates a rectangular robot using the dimensions provided in the config.json file.

Arguments:

• robotConfig (Object) – The config JSON from the config.json file.

UserPhysics.createRobotModel(robotConfig)

Override this if you want to create a custom robot model. Robot models are used to help simulate the movement of different types of drivetrains. They have a getVector method which are used to update the robot’s velocity and angular velocity in the updateSim method.

Arguments:

• robotConfig (*) – The config JSON from the config.json file.

UserPhysics.disableRobot(halData, dt)

Override this if you want to customize the physics for disabling the robot. By default the robot is stopped instantaneously.

Arguments:

• halData (Object) – A giant dictionary that has all data about the robot. See hal-sim/hal_impl/data.py in robotpy-wpilib’s repository for more information on the contents of this dictionary.
• dt (Number) – The time that has passed since the last update.

UserPhysics.init()

Override this function if you need to perform custom initialization steps in your simulation.

UserPhysics.reset()

Resets the simulation. Calls the createField, createRobot, and createRobotModel functions. If you need to add some custom behavior to the reset function, override it and call super.reset:

reset() {
  // Some custom behavior goes here:
  ...
  ...
  ...

  super.reset();
}

UserPhysics.updateGyros()

This function is called automatically. It updates the gyros in the hal data based on the angle of the robot in the simulation.

UserPhysics.updateHalDataIn(key, value)

Use this to update the hal data. Usually this is called in the updateSim function.

Arguments:

• key (String) – The path to the value you want to update in halData.
• value (String|Number|Boolean|Array) – The new value.

UserPhysics.updateSim(halData, dt)

Called when the simulation parameters for the program need to be updated. This is called approximately 60 times per second. Override this to update the velocity and angular velocity of the robot, as well as any other custom objects created in the Matter.js world that the robot can interact with. Also use this function to update the hal data if anything like sensor values change using the updateHalDataIn method.

Arguments:

• halData (Object) – A giant dictionary that has all data about the robot. See hal-sim/hal_impl/data.py in robotpy-wpilib’s repository for more information on the contents of this dictionary.
• dt (Number) – The time that has passed since the last update.