dot big bang

Scripting lets you add new behavior to games in dot big bang that didn’t exist before. It’s an extremely powerful and flexible way to make games. In this article we’ll take a straightforward overview of scripting and how it works.

Scripting in dot big bang uses a language called TypeScript. This programming language makes our scripting system easier to use, by providing useful information to the script editor. For example showing syntax errors and giving inline code hints. You can find lots of helpful tutorials and extra information on the official TypeScript website. It also has a Playground that lets you experiment with TypeScript code live in your browser.

Learning Scripting

The best way to learn to make games using scripting is to sit down and play with the editor. Invent small tasks for yourself and spend some time making them work, with all the documentation you need to one side! Start small, and you will quickly find yourself building up knowhow, and learning the ins and outs of how scripting works.

But everyone needs a little help along the way. If you’d like to talk to other people on the scripting journey, share your successes and frustrations, and have experienced developers on hand to answer questions, we have just the place. Our Discord server is a lively and friendly community where game makers, from beginners to experts, can share their knowledge and experiences, and meet like-minded people.

You’re also on our creator documentation site already. Bookmark it, because we’ll be regularly adding blogs, tutorials and other resources to help people reach their goals. We also have extensive documentation of our APIs – the scripting features the engine provides to help you build games. You can also find streams and videos about scripting on our YouTube and Twitch if you prefer video, or spoken explanations.

We also have a very useful interactive tutorial – Intro to Magic 101 – which provides explained examples of common scripts you can view in the editor and play with. In fact, most of the games on dot big bang are fully remixable, so you can save them as a new version, explore how they are made, and mod them to your heart’s content.

An Example

Here’s an example of a script that will move a turtle forwards in the direction it is facing:

class Script extends UserScriptComponent {
  // define an editor variable that controls how fast
  // this entity will move
  @numberRange(-1000, 1000)
  speed = 40;

  // tick is called every frame
  tick() {
    // grab the direction the entity is facing
    const forward = this.entity.worldTransform.getForward();

    // work out how far we traveled since the last frame
    const movementAmount = this.speed * this.game.frameDeltaTime;

    // scale our forward vector to represent our movement
    // in space
    forward.multiplyScalar(movementAmount);

    // update the entities position in space
    this.entity.worldTransform.position.add(this.movementVector);
  }
}

The tick function in the example above is a Script Callback Method. These are called by the engine whilst the game is running at specific times. They’re how the engine communicates with your scripts. There are a lot more of them and they are detailed in our Entity Lifecycle article.

Script Settings

To rename or modify the access settings for an open script you can click it's name in the tab of the script editor as shown below.

Properties

Properties, the variables on a script, will show up in the editor as long as they are public and don’t use the @hidden decorator. So if you definitely don’t want a property to be visible in the editor, prefix the property name with “private”. Here is an example of all of our property types and decorators:

    // basic types
    someNumber = 42;
    someBoolean = false;
    someString = "start text";

    @description("This decorator adds a hover tool-tip.")
    @numberRange(0, 100) // constrains the values
    anotherNumber = 10;

    @hidden() // this decorator prevents the property being visible in the editor
    aSecretProperty = "shhh";

    // a set of unique strings
    someStringSet = new StringSet();

    // math types
    someVector = new Vector3(0, 1, 0);
    someEuler = new Euler(0, Math.PI / 2, 0);
    someColor = new Color(0xFFCC00);

    // resource references
    someSkeletalAnimation = new SkeletalAnimationRef();
    someSkeletalAttachment = new SkeletalAttachmentRef();
    someSkeletalObject = new SkeletalObjectRef();

    someVoxelObject = new VoxelObjectRef();

    someSound = new SoundRef();

    // game 'things'
    someScript = new UserScriptRef();
    someEntity = new EntityRef();
    someTemplate = new TemplateRef();

Properties also take part in multiplayer games. For any multiplayer relevant Entity any public properties current state will be sent to users when they connect to a game. This can be extremely useful to catch them up with the current state of the game. For more information checkout our main Detailed Guide to Multiplayer (coming soon!).

Events

Events are the recommended route for Entities to communicate with one another but they’re also extremely useful for scripts to talk to other scripts on the same Entity. For example, Events can signal state changes to update an in-world UI to keep them in sync. Here is a quick example of how that might work:

class Script extends UserScriptComponent {
  // an editor configurable delay
  delay = 3;

  // who should we send events to?
  tagToNotify = "";

  // store how much time has elapsed
  private _timer = 0;

  tick() {
    // add the elapsed time since the last frame
    this._timer += this.game.frameDeltaTime;

    // is it time to fire the timer?
    if (this._timer < this.delay) {
      return;
    }

    // reset the timer, preserving any
    // extra time
    this._timer -= this.delay;

    // send an event to the entity with this script on it
    this.entity.sendEvent("timerFired");

    // has a tag been defined?
    if (this.tagToNotify === "") {
      return;
    }
    // send an event to anyone listening to the tag
    this.game.sendEventToTag(this.tagToNotify, "timerFired");
  }

  // this will be called whenever our event fires due
  // to the sendEvent call
  timerFired() {
    console.log("timer fired!");
  }
}

Debugging

We recommend using Chrome as your development environment. This is due to the developer tools being exceptionally good. You can open them with Ctrl-Shift-I or Cmd-Option-I on Mac. The Sources tab pictured below lets you navigate through the code being used by dot big bang including your scripts. It’s also a fully featured debugger that lets you watch the execution of your code and inspect all sorts of details.

We recommend reading the Detailed Script Debugging (coming soon!) article to get lots more information but here are a couple of important tips.

Finding Scripts

Scripts exist in two forms – the TypeScript code you wrote, and the JavaScript code compiled from it that is used by Chrome. The debugger conveniently understands the relationship between the two, so you can debug using your TypeScript code. Here’s a view showing the where both can be found, .js files are the compiled JavaScript and the .ts files are the TypeScript scripts themselves:

The TypeScript script files are found at:

dbbGameFrame -> production.dotbigbang.com -> userScript

The compiled JavaScript files are found at:

dbbGameFrame -> (no domain)

Console

The Console is a stream of text that the running code writes to. It can show messages, values and more! It’s useful for a variety of things, including some types of problems that aren’t easy to debug using the debugger. For example things happening on different players in the same multiplayer game, or processes happening over time. You can find the Console output in the developer tools under the Console tab. This provides a handy set of filters and will also report any errors or exceptions that occur in your scripts.

Where Next?

Most game features require a broad understanding of how the engine works to implement, so alongside this article we recommend you read the rest of the Basics series. We also recommend you read the Detailed series (coming soon!) as you run into specific areas you need to tackle.

Scripts are part of our Entity Lifecycle, so as someone scripting in dot big bang it’s important to understand when and where various script callback methods will be called. This also gives a rundown of our main script callbacks.

You should also check out our How To Think in DBB article which explains the common concepts we use to make games.