HOW PLAYER CONTENT WORKS IN THE SAPLING

The Sapling was built from the ground up with community interaction in mind. This interaction goes both ways: players can take stuff generated by or for the game, and use it in their own creations, or they can add their own creations to the game.

This article functions as an in-depth guide on how to do this, to be used as reference. It's a living document that will be updated continuously. If you find any things that are unclear or just incorrect, or have more ideas you want to share with other creators, drop me a line at thesaplinggame@gmail.com .

Overview of the information on this page:

1. Repurposing material from the game
   1. Music
   2. Exporting lifeforms and animations generated by the game
   3. Using gameplay statistics from the API
2. Extending the game
   1. Scenarios
   2. Body parts
   3. How to create asset bundles

1 Repurpose material from the game for your own creations

Reusing material from the Sapling for non-commercial creative purposes is highly encouraged. These three things should help with that:

1.1 Music

The music in the Sapling is generated on the fly by combining smaller parts. If you are a musician, you are encouraged to reuse them; for example in remixes and mashups. The sheet music could be the basis for covers. I'd love to see your project; let me know at thesaplinggame@gmail.com .

• Smaller musical pieces used by the procedural music engine.
• Separate layers used in the main theme.
• Sheet music for the main theme.

1.2 Exporting lifeforms and animations generated by the game

Pressing the e button in the plant or animal editor will create a .obj file in the game's persistent storage location. On Windows, this is most likely C:\Users\YourUserName\AppData\LocalLow\Wessel Stoop\The Sapling , on Mac and Linux it is probably ~/Library/Application Support/Wessel Stoop/The Sapling . The .obj file contains the 3D model of your animal, and can be imported by most (all?) 3D modeling software. In game, these models are softened with one layer of Catmull-Clark subdivision, so you might also want to do that in your modeling software.

In the animal editor, a number of .json files are also created besides the .obj file:

• ExportedBones.json, containing information on the armature the game has generated.
• ExportedBoneWeights.json, containing information on how this armature interacts with the 3D model.
• ExportedAnimation_<ANIMATION_NAME>.json, for each of the animations the game uses, containing information on how each bone moves at each point in time during this animation.

The JSON format can easily be interpreted by any programming language, so it should be easy to write a script to import it to your 3D animation software of choice. I use free animation software Blender with Python as a scripting language; a setup for importing animals and their animations can be found here.

1.3 Using gameplay statistics from the API

To get a better understanding of the way people play the game, various gameplay statistics are collected anonymously. They are saved in the form of events, logged in a separate file per IP address. Examples of events are:

• Open an editor
• Toggle the species list view
• Toggle random mutations
• Reach a milestone
• Fail a scenario

I hope to have set up this system in such way that I can turn these raw data into useful statistics as soon as I have a quantitative question in the future. However, this dataset is much too interesting to keep for myself. For that reason, the data are also available as a simple API. If you're interested, you can use this data to create things like pretty infographics, realtime dashboards, interactive visualizations, you name it.

For an overview of recorded sessions, visit olvand.com/thesapling/api.php . This will give a long lists of IDs. To see the collected events for a particular ID, you need to visit: olvand.com/thesapling/api.php?id=ID ; one line is one event. Please note that this URL will change in the near future.

2 Extending the game

To create a new scenario or a new bodypart essentially means to create a 3D model, an icon and some configuration. These files are not 'packaged' with the main files of the rest of the game, but instead in separate so-called 'Unity asset bundles'; one scenario/bodypart per bundle. You can find these bundles in the the_sapling_Data/Resources/ folder. Adding scenarios and bodyparts simply means creating more of these bundles.

Below you will find an overview of what files need to go into what bundle. Besides this overview, you can download this zip containing the files used for the bundles included in the vanilla game as an example.

2.1 What you need for a scenario asset bundle

In the game's files, the various scenarios are identified with a number: the first four main scenarios are called 0, 1, 2 and 3. This numbering is also used to order the scenarios. To prevent clashes with future main scenarios or other custom scenarios, it's probably best to give your custom scenario a 2-digit identifier.

• A terrain.fbx file with the 3D model of the terrain, as well as various other positions like where the camera positions and the clouds are. Most (all?) 3D modeling software will be able to export to FBX. The names of the various objects in the scene are important; probably the most efficient way to understand what needs to go where is to simply look at the examples included with the game, but here's a list for convenience:
  • All objects with the name 'Sea' or 'River' are given the water material.
  • All objects with names starting with 'SurfaceRock' or 'SideRock' are given the grey stone material.
  • All objects with names starting with 'Mainland' are given the brown stone material.
  • The position and size of objects (probably best: flat planes) with names starting with 'GrowArea' are used as indicators where plants can grow and animals can walk.
  • The positions of the objects with names 'CameraMainPosition', 'CameraOverviewPosition', or names starting with 'CameraPreset' are used for these respective camera positions.
  • The height of the object with the name 'CloudsPosition' determines where clouds will spawn.
  • All objects that start with 'Event' will only become visible as soon as the corresponding event (defined in the json file, see next bullet) occurs.
• A config.json file where you specify various things, like the level descpription, the objective, the various soil layers and what milestones are available. You should follow the exact format of the existing config.json files, or the game will crash.
• An 80x80px icon.png icon to be used in the main menu.
• If you specified camera presets in your terrain.fbx file, they need to have accompanying buttons to be used in the interface. Each icon has a separate image for (1) a normal state, (2) a hovered state and (3) a selected state. If you follow the naming convention rigorously, the game will figure out where to put everything automatically: preset1_hovered.png means camera preset 1, hovered state. You can specify the location of the buttons on screen in the json file.

2.2 What you need for a bodypart asset bundle

To get your bodypart working, you need to add your bundle to the correct subfolder of the the_sapling_Data/Resources/Bodyparts folder. The subfolder you choose defines as what kind of bodypart (is this a leaf or an eyeball?) your creation will be interpreted.

• A config.json file where you specify various things, like its statistics in the simulation, its place in the evolution tree, and the index of the face of the model that will be attached to the main mesh. I personally don't know of a smart way to figure out this face index; I do it by trial and error.
• A model.txt file, containing the mesh of the bodypart in a .obj format. Most (all?) 3D modeling software will be able to export to .obj . Keep in mind that the game will dynamically apply an extra iteration of Catmull-Clark subdivision, so your meshes should be simple.
• An 80x80px icon.png icon.
• If your bodypart is a limb or a mouth, an armature.json file containing information on the locations of the bones and the weights for each of the vertices. These weights define how much influence the position of a particular bone has on the vertex. This file, which also uses the JSON format, contains a list of bones, with for each bone the (1) bone name, which is used by the procedural animation system, (2) 3D position of the bone, relative to the bodypart, and (3) a list of weights for each vertex in the model.txt file. For each vertex, the weights of all bones should add up to one. Besides the main bones, it also possible to define bones for children, which are submeshes of the bodypart, like teeth.

2.3 Packaging your files into a bundle

When you have all the files you need, finally you will need to convert them to Unity asset bundles. These are the steps:

1. Download Unity. I have used Unity 2017.1.0f3, but probably any version of Unity will do.
2. Download this Unity project where everything you need is already preconfigured. Alternatively, you can set up your own by following Unity's instructions; in that case the rest of these instructions don't apply.
3. Load the folder with the files for the new scenario or bodypart into the project; for example by simply dragging it in.
4. For each of the files, select them in project window, and then go to the inspector window. Here, you should see an AssetBundle dropdown. Create a new AssetBundle for the first file, and make sure the rest of all your files are in this same bundle.
5. In the top menu, Assets > Build AssetBundles. The files will now appear in the AssetBundles folder inside the Unity project. From here, you can move them to the correct subfolder of the game files.

Published Thursday 21 November 2019