How to write a World

The basic choice is what API to use, and whether your World is controlled by a Mind or not.

---

APIs

Each World runs using a particular API. The API typically provides graphics JS libraries plus Ancient Brain libraries. Each Mind uses the API of its World.

New APIs will be added in the future. (For example, ones based on new graphics libraries.) All old APIs will be kept, so that runs always work.

The home page for each World links to the API it uses. Authors should examine the API page to see how to write for it.

As far as possible, APIs are designed so that most parts are optional. Authors can omit parts and, as far as possible, the program will still run.

See List of APIs currently installed.

---

Generate a new blank World

Most Worlds will probably be created by taking an existing working World and cloning it and then editing it.

If you want to start with a blank page, use this link (need to be logged in):

---

World screenshot

There is an image or screenshot to represent each World.

If you are the owner of a World:

• On the World page, you will see an action "Update image" to generate the image. You can run this any number of times and position the camera until you get the screenshot you want.
• By default the screenshot is taken at step 50. You can change this by setting a value for the variable AB.screenshotStep in your World code.
• You can also take a screenshot manually any time by typing AB.uploadPicture(); in the console (on an "Update image" run).

---

Upload support files

You can upload support files to use in your World:

• images (e.g. object textures)
• audio (e.g. music, sound effects)
• other (e.g. 3D models)

You upload files on your uploads page (see link on your home page). See for example the uploads page for the user Starter user.

Reference your uploads in your code using an absolute path like: '/uploads/user/file'

You can reference other people's uploads. (Though note there is a risk they will delete them.)

---

Audio autoplay on web pages

These Worlds are web pages. Audio automatically playing on web pages can be annoying. As a result, in many browsers (notably Chrome and mobile browsers) audio will not automatically play but requires user interaction to start it. The Starter Worlds that have background music have "play" and "pause" buttons for manual control if the music does not start.

A better solution is a "splash screen" to get user interaction at the start of the run, and start background music, and set up audio events that can be randomly triggered by the JS later without further user interaction. See Audio for Web games.

Here are some sample Worlds using user interaction (on a splash screen) to start background music and set up audio events for later.

• These Worlds use AB.newSplash to get a splash screen.
• See a JS code search of all Worlds for use of AB.newSplash.

How to make Chrome autoplay audio

You can change Chrome to autoplay audio:

1. Type in address:

    chrome://flags/ 

2. Search for "Autoplay policy".
3. Select "No user gesture is required".
4. Restart Chrome.

Chrome may later reset this flag, and you may have to do this again!

---

Human interaction with World - keyboard

On the desktop, you can allow the human interact with the World through the keyboard.

• Press a key to see its keycode
• See a JS code search of all Worlds for use of keycode.

Here is a sample World that reads keyboard input using keycodes. Run on desktop to see.

---

Human interaction with World - mouse

On the desktop, in our normal Three.js based APIs, mouse drag and scroll controls the camera.

If you want to use the mouse to do something else, you can override the mouse camera control, and capture Mouse events yourself in your JavaScript.

• Events
• MouseEvent

Here is a sample World showing Mouse drag for moving an agent around the World, and mouse click on an object to change it. Run on desktop to see.

• This World uses mouseDrag functions, which are support for Mouse drag and click actions provided by the API.
• See a JS code search of all Worlds for use of mouseDrag.

---

Human interaction with World - touch screen

On mobile and tablet, in our normal Three.js based APIs, touch drag and pinch controls the camera.

If you want to use touch to do something else, you can override the touch camera control, and capture Touch events yourself in your JavaScript.

• Touch events
• Pointer events
  • Pinch zoom gestures
• Introduction to Touch events in JavaScript

Below are sample Worlds showing touch drag for moving an agent around the World, and touch tap on an object to change it. Run these on mobile to see.

• These Worlds uses touchDrag functions, which are support for Touch drag and tap actions provided by the API.
• See a JS code search of all Worlds for use of touchDrag.

---

Writing instructions, help and output

For your World to write output to the screen (e.g. game instructions, help, details about the run) we suggest using these functions:

• Make a splash screen using AB.newSplash. This will vanish when the user dismisses it. See a JS code search of all Worlds for use of AB.newSplash.

• Write to areas in the run header using AB.msg. These stay on the screen. (Although the run header can be minimised.) See a JS code search of all Worlds for use of AB.msg.

You can also write instructions for authors at the top of the JS code. Only authors will look at this.

---

The "tweaker's box"

When writing a World, you might consider users who will want to edit and customise your World. Some will have limited programming ability.

It is recommended (though not enforced) that you mark out a section at the top of the code containing the things that can be easily changed in your World by a non-programmer. We call this the "tweaker's box". What is below the "tweaker's box" will need programming skills to change.

For examples of the "tweaker's box" concept, see many of the Starter Worlds. See a JS code search of all Worlds for tweaker's box.