What is Blackstone?

Blackstone is a programming language designed by the DF community, for the DF community. It is intended to be used in DF plots with high amounts of code. Blackstone aims to change how DF code is written by adding new features on top of it. These features include:

  • Function Parameters
  • Object-Oriented Programming
  • Enums
  • Select-Object Model

And more! Read further to learn more about Blackstone.

Technical Details

Here are some nice technical details to know:

Blackstone may occasionally "panic". This is because it is written in Rust! If your Blackstone compiler panics, send us the following on the Discord:

  • What code you gave it
  • The panic error & stacktrace.

If you believe an error is not helpful, please let us know on the Discord. We want to make Blackstone as friendly of a programming language as possible for developers.

Hello, Blackstone!

The first thing you will want to do is create a new Blackstone project.

$ bl init

This will initialize a new Blackstone project with some files:

  • Blackstone.toml
  • /scripts directory Blackstone.toml will hold the metadeta of your project, and will look something like this:
[box]
name = "unnamed"
author = "unnamed"

Don't worry too much about the Blackstone.toml right now. Go into the /scripts directory and create a new file.

$ cd scripts
$ touch main.bls

This will create a new file in the scripts directory named main.bls. This is where your code will be placed. Add the following code:

event player.join {
    player.sendMessage("Hello from Blackstone!");
}

Next, you will want to compile the code. It will automatically send through Recode.

$ bl build

Wait a moment and it should appear ingame for you to place. And now, you just built your first program in Blackstone! Congratulations!

Code Explanation

Let's review exactly what is going on in this example.

event

Right off the bat, we are telling the compiler we want to create an event. We specify that it is a player event with the Join event with

event player.join

However, what code should go inside of the event? We will use brackets to denote a series of code blocks.

event player.join {

}

And now, we need to send a message with "Hello, world!" inside. We want to specify that we are doing this action on the player and that we will send a message.

player.sendMessage

To specify what arguments an action has, you will want to add a Text to the action. We can do this by wrapping our text in quotes (").

"Hello world!"

Now, let's combine them into one action.

player.sendMessage("Hello world!);

Notice the semicolon. Semicolons dictate whenever there's a new action. Not using semicolons will result in a syntax error, and the compiler will be unable to parse your code. If your familiar with programming on DF, you will notice that all of the actions (sendMessage, giveItems) are just like DF's actions but in camel case. This is intentional to keep the code familiar and usuable. But after all of this, you now have a working program. Let's do something more advanced.

Diamond Fire

Now we will recreate the DiamondFire tutorial in Blackstone. In their tutorial, they give you a diamond that launches a fireball. Let's recreate this behavior. Here's the code skeleton if you want to skip ahead:

event player.join {
    player.giveItems(item(diamond));
}

event player.rightClick {
    player.launchProj(item(fire_charge));
}

Let's break this code down into it's individual components.

event player.join {
    player.giveItems(item(diamond));
}

This is similar to our first example. When the player joins, give them a diamond. However, notice the item(...) syntax. This syntax represents creating a vanilla item. You can also use items(...) syntax - it accepts two fields, an item ID and the amount of items you want to give. Both of those assume the item(s) has no special NBT except what it comes with in vanilla.

event player.rightClick {
    player.launchProj(item(fire_charge));
}

On this one, we tell the compiler we want to register an event that activates when a player right clicks. When that event occurs, have the player launch a fireball. You can tell as it's in a launchProj action and the item is a fire_charge representing a fireball ingame.

As you can see, Blackstone is quite similar to DF coding. But don't let this fool you. Blackstone has a lot of extra features that DF doesn't have. But we'll go over those later.

Common Concepts

This chapter is about concepts that are common on DF. This includes:

  • Variables
  • Functions & Processes
  • Control Flow
  • Comments