StudyCrafter

This tutorial course will teach you the basic steps needed to create your own StudyCrafter project. You don't need to know anything about StudyCrafter to take this course. After completing this tutorial, you will know:

• How to create a new Project and add new Scenes
• How to add characters, objects, and backgrounds to your Scenes
• How to use StudyCrafter scripting language to make your game run
• How to tie multiple Scenes together into a coherent whole

Prerequisites for taking this tutorial:

• You installed the latest version of StudyCrafter (which can be found here).

Launch StudyCrafter, if you haven't already. Once it finishes loading, you should see the main screen. If this is your first time using StudyCrafter, that screen will look like this:

IMG: StudyCrafter Main Screen (Over the course of working with StudyCrafter, this screen will be filled up with all the projects you make.)

Click the New Project button to create a new blank StudyCrafter project. Then, click anywhere on that project except the three buttons at the top to go into the Project Editor.

IMG: Project Editor (A completely blank project, waiting to be made.)

First, let's name the project. Click on the white box currently labeled 'New Project 1', below 'Project Name:', and type in a name of your choosing. This is the name the project will have on the main screen! If you want, you can also write a short project description in the box below this one. This description can only be seen by people who enter the Project Editor: It can be helpful to remind yourself of what your project is about.

IMG: Name/description

Now, let's make the project's first Scene. Scenes are the heart of a StudyCrafter game. You can think of them like movie scenes: Each scene takes place in a location, each scene can have actors and props, and each scene follows a predetermined script. However, unlike movie scenes, you can change your StudyCrafter scenes at any time, however you want.

Click on the New Scene button. StudyCrafter now automatically takes you into the Scene Editor.

IMG: Scene Editor (This is where you'll do most of the hard work making projects.)

When entering the Scene Editor, you start out on the Layout tab, as shown at the top of the screen. In this tab, you can decide what your scene looks like, and which 'characters' and 'assets' are in it. This is all done using the bar on the left side of the screen.

Let's start by adding a character. If StudyCrafter isn't currently showing the Character bar (see image above), click on the word 'Characters' in the top left corner.

You can add a character to the scene by clicking on it; StudyCrafter will put it in the center of the current scene. You can also click-and-drag the character onto the canvas, and place it wherever you want.

Add <certain character> to the scene.

IMG: Character to scene (Your screen should look like this.)

Even after placing, you can move the character around the screen by clicking in the center and dragging them around.

The character will be surrounded by yellow lines and boxes. By clicking and dragging the boxes, you can resize the character in any dimension you want. You can rotate the character by clicking and dragging the yellow circle to the right of the character.

IMG: Character moved, resized, rotated (You have complete control over where your character goes.)

While there are only twelve characters in the bar, you can use the black-and-white numbers and arrows at the bottom to browse StudyCrafter's large library of characters. Feel free to add more characters to your scene.

There is no limit to the amount of characters you can use. However, any character that is not placed on the scene background will not show up in-game.

IMG: Character off-screen (<character> will be visible, but <character> will not.)

Next, let's add some objects. Click on Assets in the top left corner to swap to the Assets bar. Here you can add objects to the scene, exactly the same as how you added characters.

Add <object> to the scene. Remember: You can do this either by clicking on it in the bar (which will automatically place it in the center of the screen), or by clicking-and-dragging it from the bar to your scene.

IMG: Object (If your scene has more characters at this point, that's not a problem.)

The Assets bar has a drop-down menu with three options: Objects, Background, and Interface (Advanced). Select Background from this menu. The bar now shows a number of scene backgrounds you can use. You can see that the top left option is the background your scene currently has.

You can select a new background by clicking on it. Unlike with characters and objects, backgrounds are not designed to be dragged or positioned. A new background you select immediately replaces the old one.

IMG: New Background (Simple backgrounds are easy to work with. Complex backgrounds can help establish a scene. Always use the right background for your game.)

If you click on the Play button in the top, you can see what your current game screen looks like when it is actually played. Use this to make sure everything looks right!

IMG: Play Screen 1 (Since the play screen is larger than the Layout Tab screen, try to make sure that all your characters and assets still look good.)

Now that you know how to add characters, objects, and backgrounds to a scene, let's learn what we can do with them. Click on 'Scriptor' in the top of the screen, which will take you to the Scriptor tab.

IMG: Scriptor tab (This is what that will look like initially.)

In the Scriptor tab, you write the script for your game: You define all the text that is shown, all the animations that happen, and all the actions the player can take. You do this by creating nodes, and connecting these nodes.

The Start node always exists in every project. You'll have to add other nodes yourself.

Double-click anywhere on the main screen (the black grid) to show the Node Menu, which looks like this:

IMG: Node Menu (Everything you can do to make StudyCrafter tick.)

First, let's make some text appear. Create a Dialogue node:

IMG: Empty Dialogue Node (All nodes are color-coded; dialogue nodes are always green.)

Click the 'enter text' box and write a text of your choosing.

IMG: Hello World box (Feel free to be more creative than this.)

Click the Play button at the top again to be taken to your scene. You'll notice that your dialogue does not actually appear. This is because all nodes in the script must be part of a graph, which connects them back to the Start node.

Click on the Scriptor button to be taken back to the Scriptor tab. Here, mouse over the rightmost grey ball in the Start node; you'll see it react when the mouse is over it. Click and hold the left mouse button, and drag away from the ball. You'll see a yellow line with arrows follow your mouse cursor. Drag this line anywhere over the Dialogue node, and release the mouse button.

If you did this correctly, the two nodes are now connected, like this.

IMG: Two nodes connected (This is the basic unit of StudyCrafter logic.)

If you released the mouse button at the wrong time, you'll instead see the Node Menu again. This is a second way of creating new nodes. If you create a node this way, it will immediately be connected to the node you started from.

IMG: Node Menu Redux (This can be quicker, but there's no right or wrong.)

After connecting the Start node and Dialogue node, click the Play button again. Your text will now appear.

IMG: Text appears (Congratulations, you're officially a script-writer.)

Let's make a small change. The Dialogue box has a drop-down menu called 'speaker'. If you open this by clicking on it, you see a list of all characters and assets in the current scene. You can assign the dialogue to any of them, and StudyCrafter will make it look as though that character / object speaks your text.

Assign the dialogue to <character> by selecting <character_ID> in the menu. If you are ever unsure which identifier belongs to which character or asset, you can go back to the Layout tab and look up their formal ID in the selection bar on the left.

Now click the Play tab again.

IMG: Character speaks (This is how StudyCrafter assigns text to characters.)

Now assign the dialogue to <object> instead (using <object_ID>) and click the Play tab again.

IMG: Object speaks (StudyCrafter makes no difference here. If you want your objects to 'speak', you can do that.)

Create a second Dialogue node and connect it to the Start node (using either method). You'll see that only one node can be connected to Start. To use multiple nodes, they must instead be connected to each other.

For each node, grey balls on the left mean 'input' and grey balls on the right mean 'output'. StudyCrafter always starts at the Start node, and follows connections from input to output, essentially following the arrows from start to finish.

Connect the right-output of the second Dialogue node to the left-input of the first Dialogue node. Give the second node text, then click the Play button. You'll see that the text of the second Dialogue node appears first: Since you linked the Start node to this one, StudyCrafter reads it first. In order to move from that Dialogue node to the next one, and see the second line of text, you'll have to click the left mouse button anywhere on the screen.

IMG: Nodes (Any number of nodes can be connected this way.)

All nodes, including the starting node, can be moved around by clicking and dragging any part that isn't an output ball or a button/text box/dropdown menu. You can order your nodes however you want: The yellow arrow lines determine the logic of your scene.

If you want more space to place nodes, you can zoom out (and in) using your mouse wheel, or the + and - buttons in the bottom right. You can also move the screen around by clicking and dragging empty space. The third button in the lower right centers the screen on your project's Start node, allowing you to find it again if you get 'lost'.

IMG: far zoom (Note that if you zoom out too far, the content of the nodes gets replaced with a simple descriptor. You'll have to zoom in again to be able to interact.)

So far, all you've created is dialogue a player can click through. Now, let's give the player a choice option. Create an orange 'Player Choice' node connected to the second Dialogue node.

IMG: Player choice (This is one way that could look, though again, your nodes can be ordered any way.)

A simple choice gives the player two button options: 1 and 2. You'll see that the Player Choice node has two right-output balls, meaning it can link to two different nodes. If the player picks option 1, the game continues on the line from option 1, ignoring node 2. If the player picks option 2, node 1 is ignored instead.

Create two new Dialogue nodes, give them text, and connect one to option 1 and one to option 2. Also enter text in the two 'button text' boxes; this text will show up on the buttons.

IMG: Player Choice done (Follow this example or write your own text.)

Now play your project again, and verify that both choices lead to the dialogue you wrote for them.

Right now, your StudyCrafter project only has one scene. You can create and connect multiple scenes. Each scene has its own background, characters, assets, and script, and you can use the script to define when one scene should move into another.

Click on the 'Back To Project' button in the top right. This takes you back to the Project Editor, which now contains your first scene.

IMG: Project Editor redux (The image on the scene will match the assets and characters you chose.)

Create a second scene by clicking the New Scene button. As before, this will create a scene consisting of only the standard background.

Now click the Back To Project button to go back to the Project Editor. Note that the new scene you made has a black background: Until you make your first change, StudyCrafter shows 'empty' scenes like this.

IMG: Project Editor Expanded (If you did make any changes before going back, you'll see a snapshot of the new scene.)

Click on the first scene and go into the Scriptor tab. Create a new 'End Scene' node and connect it to the open Dialogue node following Player Choice 1.

IMG: End Scene added (This is what that will look like.)

Click the Play button. You'll notice that if you select choice 1, the game ends after reaching this dialogue. An End Scene node that is not otherwise specified ends the game; this is the only way a game can end.

IMG: End Game (If you don't add one of these, the game will just keep running statically.)

Now go back into the Scriptor and select the drop-down menu on the End Scene node. This will allow you to transition from this scene to any other scene. Select Scene 2.

Now play the game again. After making choice 1, your game will transition into the second scene. After this transition, the game will use the logic in Scene 2's Scriptor, starting from that scene's Start node.

Congratulations! You now know the basics of: Creating scenes, adding and modifying assets in a scene, creating scripts to animate the scene, and linking scenes into each other or ending the game. You now have enough of a basis in StudyCrafter to explore by yourself. Try adding different kinds of nodes, or playing with the options this tutorial didn't explicitly address!

If you want more guidance, consider the following options:

Tutorial 2 will show you how to design a scientific experiment in StudyCrafter, using a well-known scientific study as an example: The Decoy Effect.

Tutorial 3 will teach you what variables are in the context of StudyCrafter, and how to use these variables to change your scenes, do calculations, and carry player choices from scene to scene.

Tutorial 4 will teach you the ins and outs of every StudyCrafter node.

The User Guide contains descriptive guides on every aspect of StudyCrafter. If you want to quickly look up the details or attributes of a specific thing, look here!

Finally, if the terminology in this tutorial or anywhere else on the wiki is unclear, the Glossary explains everything.

This tutorial course will teach you how variables work in StudyCrafter. After completing this tutorial, you will know:

• How to edit asset variables in the Layout tab
• How to edit asset variables in the Scriptor tab
• How to create and use your own global variables
• How to use variables to track player progress across scenes

Prerequisites:

• You installed the latest version of StudyCrafter (which can be found here).
• You have an understanding of the basics of StudyCrafter (from completing Tutorial 1 or otherwise)

Launch StudyCrafter, if you haven't already. Create a new project, and create a new scene inside that project. Make sure you are looking at the Layout tab.

IMG: Basic Layout Tab

Add a character asset to the scene.

Now, click on the 'Layers' button in the top right corner. Doing so opens up the Layers bar on t he right, as seen below:

IMG: Layers Bar

The Layers bar contains a list of every character, object, and background asset in the scene. Note that the bar also has several buttons to manipulate (mirror/flip/reorder) assets. This tutorial does not address these buttons, but you can learn about them in the User Guide <link>.

Select your character on the main screen. Notice that when you do this, the character's name in the Layers bar lights up red.

IMG: red name (The combination of 'red name' and 'yellow box around the asset' reliably show you which asset you have selected.)

Double-click the character's name in the list. You can now rename the asset.

IMG: rename asset (You can give your assets identifiers that better fit the study you are designing.)

Click the Edit button next to the asset's name. This will open up a list of variables for the asset.

IMG: asset variables

Asset variables describe the asset's look and position on the screen. All of these variables can be edited by moving/resizing the asset the way you're used to, but they can also be edited directly in this screen.

The variables POS.X and POS.Y determine the asset's horizontal and vertical position, relevant to the center of the screen. Setting POS.X to 0 means the asset is in the horizontal center: Positive values move it to the right, negative values move it to the left. Setting POS.Y to 0 means the asset is in the vertical center: Positive values move it up, negative values move it down.

Try editing your asset's POS.X and POS.Y values directly, and see what this does to its location on-screen.

IMG: asset POS.X edited (Compared to the above screen, this asset has moved 100 pixels to the left.)

The variables WIDTH and HEIGHT determine the asset's width and height, in pixels. Changing these is identical to resizing the asset using the outline boxes.

Try editing your asset's WIDTH and HEIGHT directly. Note that unlike using the corner boxes directly, editing WIDTH does not automatically change HEIGHT to match or vice versa. If you want to resize while maintaining aspect ratio, be careful.

IMG: poorly stretched asset (And remember that StudyCrafter currently has no UNDO function.)

The variable ROTATION determines the asset's rotation, in degrees. The number is relative to the asset's 'normal' upright position: A rotation of 0 means the asset looks the way it looks in the asset bar.

Try editing your asset's ROTATION directly. Note that since the rotation is measured in degrees, you can use 90, 180, and 270 to tilt or flip your asset easily.

IMG: 360 rotation (A rotation of 360 will get you nothing, as expected.)

The variable COLOR determines the 'color mask' that is put on your asset, given as a hexadecimal RGB value.

Think of this as a colored lens you see the asset through. Normally, this variable has value FFFFFF, which means 'white': The colors of your asset are shown through a white lens. If you change if to 00000, 'black', your asset will be drawn entirely in black. By changing the value to other numbers, you can give your asset a different color tint; examples include FF0000 ('red'), 00FF00 ('green'), and 0000FF ('blue'). you can

Try recoloring your asset.

IMG: yellow (You can find hexadecimal color value charts online, or you can practice.)

The variable IMAGE determines which picture is loaded into your asset. This variable determines what your asset looks like.

You can change this variable, but be careful: You have to change it to another image name that is loaded into StudyCrafter. If you give a non-existent or incorrect name, StudyCrafter will simply load a white square in the dimensions of your asset.

IMG: incorrect load (This is what that looks like.)

IMG: color load (Unless you gave the asset a color mask with COLOR, in which case StudyCrafter will still apply that mask to the white square.)

Try changing the image loaded in your asset. If you have trouble finding the right file names, try adding another asset into your scene, then copying that asset's given name into the IMAGE variable.

IMG: change 1 (Say we add this asset, and copy its name into the first asset's field, and then hit ENTER…)

IMG: change 2 (…and presto, now we have two identical assets.)

Finally, each asset has a hidden variable called VISIBLE, which determines whether or not the asset is shown on-screen. In the Layout tab, this is not part of the variable list, but is instead shown as the eye button left of the asset name.

If the eye button is black, VISIBLE is TRUE, and the asset is shown. If the eye button is white, VISIBLE is FALSE, and the asset is not shown.

Try making your asset invisible and visible again.

IMG: Asset visible (Now you see me.)

IMG: Asset invisible (Now you don't.)

This concludes all the variables you can edit in the Layout tab.

Move to the Scriptor tab.

On the left side of the screen, you will see the Variable bar (if the bar is not visible yet, click the Variable button on the top left side). This bar tracks two kinds of variables. 'Object Variables' are the variables associated with all your assets (characters, objects, backgrounds). These are the same variables we treated in Step 1.

Each asset is represented as a grey bar with the asset name. By clicking on that bar, you expand or retract the list of variables.

IMG: asset variables

There are two changes in this list compared to the Layout Tab list. First, the variable VISIBLE is explict here. Second, each asset has a variable called PARENT, which <does something???>.

You cannot directly edit Object Variables in the Scriptor tab. If you want to do this, return to the Layout tab and edit the variables there.

The second type of variable 'Global Variables', is unique to the Scriptor tab. These variables are not associated with any assets. Your project does not have any at the start. If you want to use Global Variables, you'll have to make them.

Click the Create Variable button at the bottom left to create a Global Variable.

IMG: global variable creation (You should see this screen.)

Each variable has four attributes. First, the variable has a name: This is how you will refer to it in your study. Second, the variable has a type, which determines what sort of information it can track. StudyCrafter has four types of variables: Float <def>, Integer <def>, String <def>, and Boolean <def>.

(If the type selection list has type 'Null', please do not use it.)

Third, each variable has an initial value: The value that the variable holds at the start of each game. If you do not enter anything here, the value will be 0 (for numerical variables), FALSE (for booleans), or the character “0” (for strings).

Fourth, each variable has a kind, which determines which role it plays in your research study. For more on this, see Tutorial 2 <link>.

Let's create a simple variable to count something. Create a new variable called COUNTER. Give it type 'integer', initial value 0, and kind 'none'.

IMG: COUNTER (If you do this correctly, the variable should appear in the Global Variables list.)

Now, return to the Project Editor. Create a second scene, enter it, and go to the Scriptor tab. You will see that the Global Variable COUNTER exists in this scene as well. Global variables are scene-independent: Each global variable exists through your entire project.

IMG: scene 2 global (All the Object Variables related to objects in scene 1 are not visible here, since these are not relevant to scene 2.)

Unlike Object Variables, Global Variables can be edited directly. Double-click anywhere on the row containing the COUNTER variable. Doing so will open the Create Variable screen again, for this variable.

IMG: Create Counter (You can see that the screen immediately fills out all details for the COUNTER variable.)

Change the initial value of COUNTER to 3, and click the SET button. Be careful to not click the DELETE button: This will delete the variable instead.

Return to the Project Editor, enter Scene 1, and select the Scriptor tab. The COUNTER variable now has a value of 3. Changes to global variables always carry over to any part of the project, regardless of where the variables was originally created.

In order to change variables in-game (over time or as a reaction to player actions), you will need to use the Set Variable node. Create this node now, and connect it to the Start node.

IMG: Set Variable node (This is where we should be right now.)

You enter two things into a Set Variable node. In the first text box, VARIABLE NAME, you enter the name of the variable you want to change. You can do this in two ways: You can type the variable name directly, or you can click-and-drag the variable name from the Variables bar into the text box.

IMG: click variable

IMG: drag variable

IMG: drop variable

If you choose to type the variable name, remember two things. First, all variable names are inside curly brackets, {like this}. And second, there is a difference between Global and Object variables. You reference Global variables by name directly: To use our COUNTER variable, type {COUNTER} in the box.

Object variables must be connected to their object; simply using {posx} would not be enough, as every single object has a 'posx' variable. You must add the asset name like follows: {assetname.posx} .

IMG: assetname.visible (This holds for every variable. In general, you can reference everything using {assetname.variableyouwant}.)

In the second text box, NEW VALUE, you enter the value you want the variable to take. This value should be appropriate for your variable: You cannot enter a String or True/False value for an integer-type variable.

In the VARIABLE NAME box, type or drag the 'height' variable of your asset. In the NEW VALUE box, type 200. Then, run your game in the Play tab.

IMG: tall asset (You'll notice the change happens immediately: SET VARIABLE boxes don't take any time to process.)

Go back to the Scriptor and check the variable values for your asset. You'll see that the asset's HEIGHT value is back to normal. Variable changes done by Set Variable nodes only ever stay valid in-game; when the game is ended, everything is set back to starting conditions.

This is true for both Object and Global variables. If you want to, try this out by changing the COUNTER variable with Set Variable and running the game.

All the above has taught you how to set variable values. We will now look at how to use variables.

Delete the Set Variable node. Connect a Dialogue to the Start node, and enter the following text: The value of COUNTER is: {COUNTER}. Now run the game.

IMG: run the game (How does it KNOW)

Whenever you use an established variable name within curly brackets, StudyCrafter will replace this with the value of that variable during run time. Again, this works for both Object and Global variables.

Change the Dialogue node so that your character asset is speaking, and change the text to: My height is: {assetname.height} pixels. Use your asset's actual name in place of 'assetname'. Now run the game again.

IMG: say height (And just like that, your character is telling you about their height.)

You can also use variables for math and decision making.

Create a Set Variable node. For VARIABLE NAME, enter {assetname.height}. For NEW VALUE, enter {assetname.height}*2. Connect this box to the Dialogue box, and run the game.

IMG: large asset (A lot taller all of a sudden.)

Variable math and logic is also in certain advanced nodes, like the Branch node. To learn more about these nodes, and how to use variables to structure, track, and control your game, check out Tutorial 4: Different Nodes <link>.

Congratulations! You now know the basics of: Editing Object variables in the Layout tab, creating Global variables in the Scriptor tab, changing variables with the Set Variable node, and using variable values in other nodes.

Variables provide a wide range of options to make your game more complicated, exciting, interesting, and useful. Experiment to see what you can achieve with them!

If you want more guidance, consider the following options:

Tutorial 2 will show you how to design a scientific experiment in StudyCrafter, using a well-known scientific study as an example: The Decoy Effect.

Tutorial 4 will teach you the ins and outs of every StudyCrafter node.

The User Guide contains descriptive guides on every aspect of StudyCrafter. If you want to quickly look up the details or attributes of a specific thing, look here!

Finally, if the terminology in this tutorial or anywhere else on the wiki is unclear, the Glossary explains everything.