Describe your Game with a Castle Project File

By The Castle Team // 1-30-2019
Castle can show useful information about your game, like its title and artwork, if you add a Castle project file. This tutorial describes how Castle project files work, how to add one to your game, and how to customize it.

What is a Castle project file?

A Castle project file (for example, my-project.castle) is text file with a special format that you can write to describe your game. Here's a really simple one:
---
title: Mecha-Thunderstorm Cheesecake Gods IV
description: Mecha-Thunderstorm is back! Battle your opponents to win the title of Grand Cheesecake Master.
main: main.lua
Castle understands how to read these files, and uses them to open and display your game. They use the .castle file extension, and they are written in something called YAML, but you don't need to know much about YAML to understand them. As long as the above example makes sense, that's about all there is.

What can I do with a Castle project file?

Let's use the same one as an example, and explain each thing in it:
---
title: Mecha-Thunderstorm Cheesecake Gods IV
description: Mecha-Thunderstorm is back! Battle your opponents to win the title of Grand Cheesecake Master.
main: main.lua
The title of this game is Mecha-Thunderstorm Cheesecake Gods IV. Castle will display this title under the game while people play it, on your profile, in search results, and generally anywhere it needs to refer to your game.
image
A screenshot of the info bar below the game in Castle.
You might also notice in the previous screenshot that the description of this game is Mecha-Thunderstorm is back! Battle your opponents to win the title of Grand Cheesecake Master. Castle will use this anywhere it needs to display a longer piece of information about the game.
Lastly, the line main: main.lua tells Castle where to find the code to actually run your game. The main key refers to the lua file (relative to this project.castle file) that Castle should begin reading first, also known as the entry point for your game. This way, if you open my-project.castle file directly in Castle, it has all the information it needs to start playing.
You can customize more aspects of your game, but those are the basics. Check out the full .castle spec to see all the possibilities.

How do I add one of these to my game?

Castle automatically creates one of these for you any time you Create a new Castle Project. Take a look in your project folder and find a file called project.castle. If you don't have one and want to add one, follow these steps:
1. Copy and paste this into your favorite text editor:
---
main: main.lua
title: My Great Game
Note: Make sure that the main: key actually has the name of your entry point file. The most common name is main.lua, but if you named yours something else like my-game.lua, you might need to update it.
image
2. From your text editor, save this file as project.castle in the same directory as your game's lua code.
image
That's it! You can now open project.castle directly in Castle, and you should see the My Great Game title appear with your game.

What's Next?

You can customize more than just the title and description of your game using this kind of file. Check out the full .castle spec to see all the possibilities.
Adding a Castle project file to your game is required if you want to add your game to your Castle profile. Check out our guide on Adding Games to your Profile to learn more.