TCLE Spec WIP

TCLE File Specification 1.0.0

!! NOTICE !!
This Specification is **NOT** final and is still being written.

The TCLE File Specification and TCLE Version itself are two VERY different things. This document ONLY defined how the TCLE files must be generated. TCLE itself implement whatever it likes as long as the files adhere to this specification.

The vast majority of TCLE files are saved in JSON.

API Stability and Symver

Since the TCLE files are used to communicate between different programs created by different people. The TCLE File Specification adheres SymVer. It's highly suggested to read about this if you don't already know what it is. https://semver.org/`

Extensions

Extensions allow use to implement custom or new behavior without explicitly requiring an update to the specification. This works very similarly to how OpenGL handles extensions.

Anyone may create an extension. Extensions are simply modifications to the spec to add new features. Extensions are named by a string which is unique to the extension. Example AF_AUR_MULTILANG_TITLES.

Extensions are written against a specific version of the specification and may require a specific version range of the spec. This allows an easier time to compare and implement changes.

Extensions may be enabled using the extensions_enable field in the .tcl. Enabling an extension specifies that the behavior provided by the extensions is optional. If a tool doesn't support the extension then things will still behave.

You may choose to require certain extensions. If you specify an extension is required then if a tool doesn't support the extension then an error must be generated.

After extensions exist for some time they eventually may be promoted to a core feature in a later version of the specification. When this is the case, testing for the extension name must confirm the extension is supported.

Types

These are custom types which imply certain expectations of the value it contains. Most of the types are simply typedefs of other types.

type	typedef	info
clampf	float	Values are between the range 0 -> 1
color4f	clampf[4]	A color value encoded with RGBA order.
version	string	A SymVer formatted string

Optionals

Optionals are simply the type name appended with a ?. This denotes that the field is not required to be specified.

Enumerations

Enumerations are groups of similar values. These are used in a few locations. The list of enumerations are listed below:

Section

The section enumeration informs the thumper engine about a sublevel. TCLE only exports SECTION_LINEAR however the following values are also accepted.

• "SECTION_LINEAR"
• "SECTION_BOSS_TRIANGLE"
• "SECTION_BOSS_CIRCLE"
• "SECTION_BOSS_MINI"
• "SECTION_BOSS_CRAKHED"
• "SECTION_BOSS_CRAKHED_FINAL"
• "SECTION_BOSS_PYRAMID"
• "SECTION_END"

.TCL

The .TCL file is a singular unique file that signals this is a TCLE save. This file also contains general information about the level.

field	data type	info
level_name	string
difficulty	string
description	string
author	string
bpm	float
level_sections	Section[]
rails_color	color4f
rails_glow_color	color4f
path_color	color4f
joy_color	color4f

Spec Extensions

The specification further extends these fields for forward compatability reasons. The additional fields are listed below.

field	data type	info
spec_version	version?	Against what specification is this written written for. When omitted "1.0.0" is assumed
extensions_enable	string[]?	A list of extensions to enable support for
extensions_require	string[]?	A list of extensions to require support for

The following section has not been revised yet

Master

.master

field	data type	info
obj_type	string	SequinMaster
obj_name	string
skybox_name	string
intro_lvl_name	string
groupings	MasterLvlObject[]
isolate_tracks	bool	Used for testing WIP levels. Used in conjunction with the isolate field in MasterLvlObject
checkpoint_lvl_name	string

MasterLvlObject

field	data type	info
lvl_name	string	only lvl_name OR gate_name should be filled in. Never both.
gate_name	string
checkpoint	bool
checkpoint_leader_lvl_name	string
rest_lvl_name	string
play_plus	bool
isolate	bool	used for testing WIP levels. If .master isolate_tracks is true, then only build MasterLvlObject that have this field set to true.

---

Leaf

.leaf

field	data type	info
obj_type	string	SequinLeaf
obj_name	string	name of the leaf
seq_objs	SequencerObject[]
beat_cnt	uint
time_sig	string	only relevant for the editor

SequencerObject

field	data type	info
obj_name	string
param_path	string	The object will have param_path OR param_path_hash in the JSON, never both.
param_path_hash	string	it's a uint encoded as a string. Does not start with 0x
trait_type	string
data_points	DataPoint[]
step	bool
default	float
footer	string	comma separated values, should be parsed into an array. Example: "2,1,2,1,2,'kIntensityScale','kIntensityScale',1,0,1,1,1,1,1,1,0,0,0"
editor_data	var[]	only relevant for the editor
enabled	bool	if false, this object should not be written into the level. Used for testing/previewing changes while working on the level.

DataPoint

field	data type	info
beat	int
value	float
interp	string
ease	string

---

Lvl

.lvl

field	data type	info
obj_type	string	SequinLevel
obj_name	string
approach_beats	uint
seq_objs	SequencerObject[]
leaf_seq	LvlLeafObject[]
loops	LvlLoopObject[]
volume	float
input_allowed	bool	Is the player allowed control during this lvl
tutorial_type	string
start_angle_fracs	float[3]	typically all 1

LvlLeafObject

field	data type	info
beat_cnt	uint
leaf_name	string
main_path	string	this is usually default.path
sub_paths	string[]	names of tunnels applied to this leaf
pos	float[3]	default 0,0,0
rot_x	float[3]	default 1,0,0
rot_y	float[3]	default 0,1,0
rot_z	float[3]	default 0,0,1
scale	float[3]	default 1,1,1

LvlLoopObject

field	data type	info
samp_name	string
beats_per_loop	float

---

Gate

.gate

field	data type	info
obj_type	string	SequinGate
obj_name	string
spn_name	string
param_path	string
pre_lvl_name	string
post_lvl_name	string
restart_lvl_name	string
section_type	string	Changes how the boss sublevel displays in-game
random_type	string
boss_patterns	BossPattern[]

BossPattern

field	data type	info
lvl_name	string
sentry_type	string
bucket_num	int
node_name_hash	string	should be parsed to uint to be written. Does not begin with 0x

---

Sample

.samp

field	data type	info
items	SampleObject[]

SampleObject

field	data type	info
obj_type	string	Sample
obj_name	string
mode	string
path	string
volume	float
pitch	float
pan	float
offset	int
channel_group	string

---

Spawner

.spn

field	data type	info
items	SpawnerObject[]

SpawnerObject

field	data type	info
obj_type	string	EntitySpawner
obj_name	string
xfm_name	string
constraint	string
pos	float[3]	default 0,0,0
rot_x	float[3]	default 1,0,0
rot_y	float[3]	default 0,1,0
rot_z	float[3]	default 0,0,1
scale	float[3]	default 1,1,1
objlib_path	string
bucket	string

---

XFM

.xfm

field	data type	info
obj_type	string	Xfmer
xfm_name	string
constraint	string
pos	float[3]	default 0,0,0
rot_x	float[3]	default 1,0,0
rot_y	float[3]	default 0,1,0
rot_z	float[3]	default 0,0,1
scale	float[3]	default 1,1,1

END The following section has not been revised yet

Extensions

Here's a list of current extensions that at least one thumper tool supports.

AF_AUR_MULTILANG_TITLES

• Written against 1.0.0
• Authors: AnthoFoxo

This extension enables level creators to translate their custom level titles into all the other localizations thumper supports. Without this extension it is unspecified what should happen when the title is localized. TML simply does nothing. Aurora copies the english name to other languages.

New Fields

• Add field map<string,string> multilang_ext to .TML

This map takes the localization key as the key into the map, the value of the map is a localized string to the localization as specified by the key.

If the en key is specified in this table then this value will take priority over the level_name value.

The following values for the localization key are recognised.

• da
• de
• en
• es-la
• fi
• fr-ca
• fr
• it
• ja
• ko
• nl
• no
• pl
• pt-br
• ru
• sv
• tr
• zh-s
• zh-t