Getting started with your first ALPACA game
When you want to use ALPACA, you have two different options:
- You can use ALPACA for game development without the need to compile C++ code, only using Lua scripting and the Spine editor (Windows only)
- You can set up ALPACA for engine development, where you compile the engine (C++ code) yourself and are able to make changes to the core functionality of ALPACA (this is required on Mac and Linux, but also possible on Windows)
Setup your PC for game development (Windows)
This is the easiest way to work with ALPACA. You won't have to mess with C++ compilers and will use a pre-compiled version of ALPACA. Unfortunately, this only works on Windows.
- Get ALPACA for Windows.
- Install Spine into the default folder.
- Start
prepare_assets.exe
so your changes in the data-src folder will be synced into the data folder. - With
pac.exe
you can start the game. - In the Schnack folder you can find the dialog editor.
- For Lua Scripting it's recommand to use VS Code with a Lua extension like LuaHelper.
- Start building your game.
- If you need help setting up your first project or want to talk about your game. Book a time slot with the developers of ALPACA at calendly 🇩🇪🇬🇧, mail me at kolja@portaldogs.com 🇩🇪🇬🇧 or join ALPACA on Discord
Setup your PC for engine development (Windows / Mac / Linux)
This is the advanced way to work with ALPACA. You will compile the engine yourself. This will also enable you to make changes to the engine core, if you feel this is necessary for your use-case.
- Clone the ALPACA repository with git via
git clone --recurse https://github.com/pinguin999/ALPACA.git
or clone it with the GutHub Desktop client. - Setup your Mac or Linux for JNGL development. Or Windows development
- Now you should be able to play the demo project.
- Check that you have installed Spine, Rhubarb, Lua and Python. Now you can re-export all assets from data-src to data with the prepare_assets.py script. On Windows you need Spine installed and you can use prepare_assets.exe to export the assets.
- If you need help setting up your first project or want to talk about your game. Book a time slot with the developers of ALPACA at calendly 🇩🇪🇬🇧, mail me at kolja@portaldogs.com 🇩🇪🇬🇧 or join ALPACA on Discord
What's in the demo game?
The demo has two scenes. In the first scene is a banana and it has a funny effect if you click it. In the second scene is alpaca so you have something for your experiments there. If you press on alpacas head it's talking to you.
What you can learn from the demo game
The demo is a good starting point for a new project. It has already a working setup and some good defaults set up for you. You can also start with an empty data-src folder, but for a smooth start it's recommanded to start from the demo game.
You can play and learn from the project. Here are some tasks you can try out yourself.
All game content is in the data-src
folder and the prepare_assets
converts it and puts it into the data
folder. So never change any files in the data
folder. It should always be safe to delete the data
folder and prepare_assets
will recreate everything from data-src
.
Add a Spine object
All items in an ALPACA game are Spine objects. So to add an new item to a scene you have to start a new Spine project.
- Create a folder in
data-src
with the name of your object. Let's name itdog
- Open Spine and click
New Project
- Name the skeleton also like your folder. In our case it's
dog
again - Add images to your spine file and create nice animations.
- Save the Spine file in
data-src/dog/dog.spine
- The
prepare_assets
script should already running, if not start it. Check the output for...dog.spine has been modified
- Now open
data-src/scenes/test_chamber_one.json
in VS Code and add the dog item into the items list.
{
"items": [
{
"spine": "banana",
"x": "330.0",
"y": "400.0",
"scale": "0.3",
"skin": "normal"
},
{
"spine": "dog",
"x": "0.0",
"y": "0.0"
}
],
...
}
- The Scene should now reload and show the dog.
Find out more about scene objects and Spine
Move an object
The dog object you just created will be positioned in the center of the screen.
- In the game open the edit mode by pressing Tab
- A green circle will shown under the dog
- Drag and drop the dog whereever you want to have the dog.
- Press S to save.
Play with the scripts
Interactable regions are defined via a Bounding Box
in Spine.
- Select a
bone
in Spine and selectBounding Box
from the new dropdown. - Give the box a speaking name. The name should represent the action. Let's name it
bark
- The prepare_assets script will automaticly generate a file called
bark.lua
for you. The file will contain this line
print("bark")
- The dog will automaticly be reloaded the clickable area can be clicked.
- If you are not sure where the area is you can visulise it by pressing F10
- After clicking the area the debug console will show the text
bark
- If your dog has a bark animation you can start the animation via the script by aclling the PlayAnimation function.
print("bark")
PlayAnimation(0, "bark", false)
Now we will start with the Lua scripting, the way logic is defined in an ALPACA game. A full list of functions can be found in the Lua API documentation. For the quick intro you want the player to go to the item and interact with it. To be able to go somewhere you have to define a Point in Spine, so let's add the Point to our item and save it again. I have named the Point in the example "game center" and will also use this name in this tutorial's script.
Most Lua Function like GoToPoint
have two versions: GoToPoint and GoToPointOn
print("banana_clicked")
GoToPointOn("banana", "center", function ()
PlayAnimationOn("Player", 0, "death", false, function respawn()
print("respawn")
PlayAnimationOn("Player", 0, "idle", true)
end)
end)
For a full overview about all Lua functions see the Lua documentation
Change Dialog and play audio
ALPACA comes with the Schnack node based dialog editor. The alpaca in the demo has one dialog. You can start Schnack and open the dialog file from data-src/dialog/dialogs.schnack
Change the game config
First you should look into the data-src/config/game.json file. There you can change all important base parameters like the game name and the start_scene.
Add a new scene
Everything in an ALPACA project is organized in scenes. A scene exists out of a background, some items placed in the scene and music that will be played in the background. So let's look into the scenes folder. There you have the two example scenes. Let's copy one of the example scene files and rename it to what you set start_scene to in game.json. If you do not need the test_chambers it's safe to delete them.
In ALPACA everything you can see on the screen is a Spine project, so for the scene background you need to create a Spine project. Open Spine and click New Project and name the skeleton to your scene name. The background is drawn from the center so the Spine 0,0 point should be in the middle of the screen. If you want the player to walk in the scene you need a walkable_area
bounding box. For reference you can check out data-src/scene1/scene1.spine. After saving our scene background you should update the background entry in our scene file. If it's not already running you should start prepare_assets.py to get the files exported into the data folder. If you start your game now you should see your new scene.