📜TSL Basics

What is TSL language and how do you write it?

TwitchSpawn Language (TSL) is a data language parsed by the mod to figure how should it respond to certain events. There are a few strict syntax rules while writing your own ruleset. Let's see more about the terminology and the syntax rules.

Terminology: Word

A word is the smallest meaningful unit parsed by the mod. Words are chained in order to form rules and rulesets. Words can be chained with a SPACE character. However, words containing SPACE character can be grouped with % symbol. Let's see an exemplar sentence:

EXECUTE /kill %/gamerule doDaylightCycle false% %/tellraw @a "99.9\% Fun"%

translates into following words:

1. EXECUTE

2. /kill

3. /gamerule doDaylightCycle false

4. /tellraw @a "99.9% Fun"

Words containing the grouping symbol (%) can use escaping symbol (\) to escape its special grouping semantic. (E.g %word with \% in it% translates into only 1 word which is word with % in it.)

Terminology: Comment

Comments are an important part of the programming world. They serve the functionality of leaving notes in the code. They basically are ignored by the parser, but still visible to the programmers/writers. Just like other programming languages, TSL can get very messy easily. In order to keep your rulesets clean, you can put comments by following syntax:

# This is a one-line comment. Will be ignored by the TSL parser!

#*
 This is a multi-line comment
 Anything
 Written
 Between
 Those Symbols
 Will be Ignored!
*#

Terminology: Rule

A rule consists of three fundamental parts: Action, Event and Predicates.

Rule infrastucture represented as a puzzle analogy

Action (such as DROP) defines what to do, Event (such as Twitch Follow) defines when to do, Predicates (such as viewers > 10) define under which conditions to do.

Predicates are words as well. They are seperated into 3 parts: property (such as viewers), comparator (such as >=) and a literal value (such as 10). Therefore a SPACE character is ALWAYS required between those parts. (E.g viewers>=10 predicate counts as malformed because of the lack of SPACEs inbetween.)

Those parts come together to compile following syntax:

<ACTION> [action parameters depending on the action] ON <Event Name> {WITH <Predicate>}

example#1

DROP minecraft:stick ON Twitch Host WITH viewers > 10

example#2

DROP # You can put a new line after each meaningful word
 %stick{display:{Name:"\"Stick of Truth\""}}% 2
 ON Twitch Follow

example#3

EXECUTE %/kill @e[type=item]% # Remove all the items
 ON Donation # When a donation occurred
 # With donation amount between 10 and 20
 WITH amount > 10
 WITH amount < 20

You can spread one rule declaration into multiple lines by a NEW LINE and SPACE character (See example#2 and example#3). But be careful, new lines without a SPACE character will be interpreted as malformed rules and will throw an error on loading.

Also depending on the rule, you can use DISPLAYING keyword to override default message displaying logic. Exemplar rule:

THROW slot 3 FROM armors
 DISPLAYING %["Say good-bye to your helmet!"]%
 ON Donation WITH amount > 10

Terminology: Ruleset

Ruleset infrastucture represented as a puzzle analogy

A ruleset is a self-explanatory term which is a collection of rules. Rulesets (basically .tsl files) declare the whole response logic. Their syntax is pretty easy, rules are separated with blank lines

example#1

DROP stick ON Donation WITH amount IN RANGE [0,10]

DROP diamond ON Donation WITH amount IN RANGE [11, 20]

DROP emerald ON Donation WITH amount >= 21

example#2

EITHER
 NOTHING # Does nothing, but still displays message!
 OR DROP diamond 2
 ON Twitch Follow

# Comment after a blank line
EXECUTE %/weather thunder%
 DISPLAYING %[{text:"The weather is stormy today!", color:"dark_purple"}]%
 ON Twitch Raid
 WITH raiders > 100

# From ToastNomNomNom's Command Block Works
EXECUTE %/effect give @p minecraft:blindness 30 255%
 %/playsound entity.enderman.death player @p ~ ~ ~ 10 .5%
 %/summon chicken ~8 ~10 ~8 
  {Passengers:[{id:wither_skeleton,PersistenceRequired:1,Silent:1,HandItems:
  [{Count:1,id:diamond_sword,tag:{Enchantments:[{id:sharpness,lvl:5},
  {id:knockback,lvl:2},{id:fire_aspect,lvl:2},{id:unbreaking,lvl:3}]}},
  {Count:1,id:shield,tag:{Enchantments:[{id:unbreaking,lvl:3}]}}],
  CustomName:"\"Chicken Rider of Doom\"",ActiveEffects:
  [{Id:1,Amplifier:1,Duration:999999},{Id:5,Amplifier:1,Duration:999999},
  {Id:10,Amplifier:1,Duration:999999},{Id:11,Amplifier:0,Duration:999999},
  {Id:12,Amplifier:0,Duration:999999},{Id:21,Amplifier:0,Duration:999999},
  {Id:22,Amplifier:0,Duration:999999},{Id:23,Amplifier:0,Duration:999999},
  {Id:28,Amplifier:0,Duration:999999}]}]}%
 ON Twitch Host
 WITH viewers >= 100

default

# Example TSL (TwitchSpawn Language) Rule Set
# Feel free to edit this one, or create your own rule set!
# For full documentation about TSL Language
# See https://igoodie.gitbook.io/twitchspawn/

# Donation Rules
DROP minecraft:stick 2
 ON Donation
 WITH amount IN RANGE [0,20]

DROP minecraft:diamond_block 1
 ON Donation
 WITH amount IN RANGE [21,999]

EXECUTE %/gamerule keepInventory true%
 ON Donation
 WITH amount >= 1000

# Follow Rules
DROP %diamond{display:{Name:"\"99.99\% Percent Real Diamond\""}}% 2
 ON Twitch Follow

# Host Rules
EXECUTE %/give @s stick 1%
 ON Twitch Host
 WITH viewers >= 10

# Raid Rules
EXECUTE %/weather thunder%
 ON Twitch Raid
 WITH raiders > 100

There MUST be at least one blank line between rules. Lines followed by non-empty lines are considered as one (included the commented lines). So be careful not to put ONLY comment lines without a blank line between rules.

Following example is considered as a malformed ruleset due to the lack of blank line delimiter.

DROP stick ON Twitch Host WITH viewers = 10
# A comment between
DROP diamond ON Twitch Host WITH viewers = 20