This is a quick run-down of how to create games for TwoCans
This is still being actively developed, so please be patient as there are lots of rough edges with this tech stack. If you run into a problem, there's a good chance it's a problem on my end, so please let me know if you run into any hiccups!
Don't Be Shy
There are a few places where you can mingle and casually ask for help.
For TwoCans Developer related stuff, the TwoCans Game Dev Slack is the most specific channel for this purpose.
If you're already a member of the general purpose TwoCans Telegram chatroom, that's pretty active as well and there's quite a bit of overlap with the Slack channel membership.
If all else fails, please message me directly.
Prerequisites
This tutorial assumes you are familiar with the following:
- You know how folders and files work on your computer.
- You know how to use the command line.
- You know how to set environment variables on your computer.
- You know how to use git and GitHub and have your own GitHub account.
Crayon
Game widgets are written in Crayon. It is a programming language that is similar to many curly-brace based languages and resembles a more strict JavaScript or a dynamically typed Java. However, unlike Java, Crayon can run in the browser without a plugin and, unlike JavaScript, can do so securely.
If you already know a programming language or two, learning Crayon is quite easy and can be done so with the Intermediate Tutorial. If you are brand new to programming, check out the Beginner's Tutorial.
Setting things up
Windows Instructions
You can download Crayon from TwoCans directly. When you extract this zip file, add an environment variable called CRAYON_HOME which points to the directory where crayon.exe is located. Then add %CRAYON_HOME% to the end of the PATH environment variable (typically delimited with a semicolon if your UI doesn't already delimit them).
Mac Instructions
Contact me!
Getting the SDK and Sample Projects
Clone or download the TwoCans git repository. There are two notable directories in this repository: api and demos. First create an environment variable called TWOCANS_SDK that points to the api directory. Using the command line you can now navigate to the individual demo directories and run those projects using the following command line commands:
C:\Stuff\twocansandstring\demos\SimpleProject> crayon SimpleProject.build
If it runs, then congratulations! You have set everything up propertly and are ready to create your own project.
Creating a Project
All TwoCans games must be submitted as GitHub repository links. This is currently a requirement, although more options for submissions will hopefully be added later.
That means the next step is to create a new GitHub repository. This repository must be public. Even though you can generate empty projects using crayon -genDefaultProject on the command line, do not do this. There are many required fields that need to be added to the build file in order for it to be a valid TwoCans project. The easiest way to create a new project is by simply copying the SimpleProject from the demos and pasting it into your repository. Rename SimpleProject.build to your own project name
Now you must open the file using a plain text editor and edit the contents. Crayon build files are just JSON files. Change the following fields:
- id - this should be the name of your project without spaces or special characters.
- title - this should be the name of your project. Spaces and special characters are allowed.
- desccription - a short description of your project.
- guidseed - this is a seed to generate a fingerprint that uniquely identifies this project and version. The standard practice is to include the name of a domain name that you own as a prefix (in reverse order with the TLD first, e.g. com.mywebsite) to prevent the possibility of colliding fingerprints. If you don't have a domain, you can use com.twocansandstring.users.{your twocans username} or just put something unique and silly instead.
- vars - In this variable list, there are a few things you need to modify.
- screen_width and screen_height - This will be the size of the window. There are a few constraints for this, though. The width must be at least 256 and at most 1024 and the height must be at least 224 and at most 600. This is to ensure that the widget fits decently within the available area. Additionally, neither dimension can be more than a factor of 2 of the other dimension.
- game_title - this should be the same as the title above.
- initial_scene - A game is a collection of scene objects. If you keep the MainScene name, you don't have to modify this, although you may want something like TitleScene later.
- enable_wasd - When set to true, this will make the W, A, S, and D keys report events to your code as though they are arrow keys.
You can now start coding your project!
Documentation for the specifics of the SDK can be found on the documentation page.
Submitting Your Game
Create or Add to a Git Repository
Create a git repository for your game. This repository must be public.
Commit and push all your Crayon code to this repository.
Dev Dashboard
After everything is pushed and public, go to the Dev Dashboard and click "Add New Project".
Choose a name for your project. This value cannot be changed without creating a new project. Provide the link to your github repository. This does not need to be a link to any specific file within the git repository or the .git file itself. Simply a link to the repository. The format should be something like https://github.com/yourGitUserName/yourRepositoryName. This value can be changed later so don't worry if you mess up or have intentions to move your repository somewhere else.
After you push the "Create Project" button, this will take you back to the dashboard, which now has an entry for your game. Click the "Add/Edit" link.
There is a single button for adding a new version with various fields above it. If your repository has the build file in the root directory and only uses the default master branch, there's nothing to do here! If you have multiple build files or the build file is nested within another directory, or you have a specific build target with special options you want to use for TwoCans only, you can specify those options here. Otherwise, just push the "Create New Version" button.
This tells TwoCans to take a snapshot of the code from your repository as it currently is and compile it. Reload the page after about 20 seconds. WARNING/BUG ALERT: please be careful to reload by pressing enter on the URL bar and not simply hitting F5 or the refresh button. Reloading the page will re-submit the version. I will fix this at some point.
If all goes well, the status column will be marked as "Complete". If not, there will be an error. If the error should give you an indication of what went wrong. If you are totally confused about the error message, contact me.
Testing and Publishing
If it did complete, you can now click on the link in the ID# column. This will take you to a page where you can play your game in the browser. If all looks well, click "Edit" for that version. On the next page, check the box that says "Is Stable" and update the version. This now makes your game public, at which point your game can be seen on the Games page.
