HSON Format - Revision history

Hyper at 21:16, 1 May 2026

2026-05-01T21:16:55Z

← Older revision		Revision as of 21:16, 1 May 2026
Line 520:		Line 520:
	• <code>"myCustomEditor/presetPlacementType": "LINE"</code>		• <code>"myCustomEditor/presetPlacementType": "LINE"</code>
	• <code>"myCustomEditor/presetPlacementDistance": 1.0</code>}}		• <code>"myCustomEditor/presetPlacementDistance": 1.0</code>}}
			[[Category:File Formats]]

Hyper: Fixed hson-schema repository link

2025-07-13T00:16:44Z

Fixed hson-schema repository link

← Older revision		Revision as of 00:16, 13 July 2025
Line 8:		Line 8:

	== JSON Schema ==		== JSON Schema ==
	The official JSON Schema for the HSON Format can be found at the [https://~~hedgedocs~~.com/~~docs/general~~/hson/ hson-schema GitHub repository].		The official JSON Schema for the HSON Format can be found at the [https://github.com/hedge-dev/hson-schema hson-schema GitHub repository].

	It's useful (but not necessary) to validate .hson files against this schema in editors which support this feature, as doing so allows you to have autocompletion, descriptions of each property, and data validation.		It's useful (but not necessary) to validate .hson files against this schema in editors which support this feature, as doing so allows you to have autocompletion, descriptions of each property, and data validation.

PTKay: Undo revision 63 by PTKay (talk)

2025-02-14T11:23:19Z

Undo revision 63 by PTKay (talk)

← Older revision		Revision as of 11:23, 14 February 2025
Line 508:		Line 508:
	</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>		</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>

	* Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with [[HSON Format#3.6. position\|HSON's position property]]).		• Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with [[HSON Format#3.6. position\|HSON's position property]]).
	* Empty strings		• Empty strings
	* Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:		• Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:
	<syntaxhighlight lang="json">		<syntaxhighlight lang="json">
	"myCustomEditor": {		"myCustomEditor": {

PTKay at 11:22, 14 February 2025

2025-02-14T11:22:46Z

← Older revision		Revision as of 11:22, 14 February 2025
Line 508:		Line 508:
	</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>		</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>

	• Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with [[HSON Format#3.6. position\|HSON's position property]]).		* Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with [[HSON Format#3.6. position\|HSON's position property]]).
	• Empty strings		* Empty strings
	• Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:		* Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:
	<syntaxhighlight lang="json">		<syntaxhighlight lang="json">
	"myCustomEditor": {		"myCustomEditor": {

PTKay at 11:12, 14 February 2025

2025-02-14T11:12:17Z

← Older revision		Revision as of 11:12, 14 February 2025
Line 310:		Line 310:
	</syntaxhighlight>		</syntaxhighlight>

	In this snippet from the example file, the object has specified a position of <code>[ 0.0, 1.0, 0.0 ]</code>, and a parentId of <code>{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}</code>, which means that its transform is local to the transform of the object which uses that UUID (not included in this snippet).		In this snippet from [[HSON Format#Example\|the example file]], the object has specified a position of <code>[ 0.0, 1.0, 0.0 ]</code>, and a parentId of <code>{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}</code>, which means that its transform is local to the transform of the object which uses that UUID (not included in this snippet).

	This parent object has a position of <code>[ 100.0, 0.0, 0.0 ]</code>.		This parent object has a position of <code>[ 100.0, 0.0, 0.0 ]</code>.
Line 322:		Line 322:
	</syntaxhighlight>		</syntaxhighlight>

	In this snippet from the example file, the object has specified a parentId of <code>{00000000-0000-0000-0000-000000000000}</code> (the special UUID null value), which is equivalent to not specifying a parentId. This means that this object has no parent.}}		In this snippet from [[HSON Format#Example\|the example file]], the object has specified a parentId of <code>{00000000-0000-0000-0000-000000000000}</code> (the special UUID null value), which is equivalent to not specifying a parentId. This means that this object has no parent.}}

	==== 3.4. instanceOf ====		==== 3.4. instanceOf ====
Line 358:		Line 358:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	In this snippet from the example file, the second listed object (UUID: <code>38285a58-9969-4c5f-a649-b91440962a71</code>) is an instance of the first listed object (UUID: <code>2737e92f-4842-46cb-a590-e074f7b882f0</code>).		In this snippet from [[HSON Format#Example\|the example file]], the second listed object (UUID: <code>38285a58-9969-4c5f-a649-b91440962a71</code>) is an instance of the first listed object (UUID: <code>2737e92f-4842-46cb-a590-e074f7b882f0</code>).

	As such, it will inherit all of the unspecified properties from the first object, including the <code>parentId</code>, <code>type</code>, <code>myCustomValue</code>, and <codemyCustomEditor</code> properties, as well as the visibility parameter.		As such, it will inherit all of the unspecified properties from the first object, including the <code>[[HSON Format#3.3. parentId\|parentId]]</code>, <code>[[HSON Format#3.5. type\|type]]</code>, <code>myCustomValue</code>, and <codemyCustomEditor</code> properties, as well as the visibility parameter.

	It will <b>NOT</b>, however, inherit the specified properties, including the <code>id</code>, <code>instanceOf</code>, and <code>position</code> properties, as well as the <code>respawnTime</code> parameter.		It will <b>NOT</b>, however, inherit the specified properties, including the <code>[[HSON Format#3.1. id\|id]]</code>, <code>[[HSON Format#3.4. instanceOf\|instanceOf]]</code>, and <code>[[HSON Format#3.6. position\|position]]</code> properties, as well as the <code>respawnTime</code> parameter.

	This means that the second object in the above snippet will be equivalent to the following object:		This means that the second object in the above snippet will be equivalent to the following object:
Line 395:		Line 395:
	}		}
	</syntaxhighlight>		</syntaxhighlight>
	The second object listed in the above example will inherit all properties from the first object, <i>except</i> for the <code>id</code>.		The second object listed in the above example will inherit all properties from the first object, <i>except</i> for the <code>[[HSON Format#3.1. id\|id]]</code>.

	This is due to the fact that every valid object must have its own unique UUID.}}		This is due to the fact that every valid object must have its own unique UUID.}}
Line 402:		Line 402:
	{{Notice\|type=info\|content=• <b>Type</b>: string		{{Notice\|type=info\|content=• <b>Type</b>: string

	This value is <b>REQUIRED</b> to be present, <b>unless this object is an instance of another object</b>, in which case, it is optional, as the type will just be taken from the instanced object.}}		This value is <b>REQUIRED</b> to be present, <b>unless this object is an [[HSON Format#3.4. instanceOf\|instance of]] another object</b>, in which case, it is optional, as the type will just be taken from the instanced object.}}
	'''The type of the object''' (e.g. "Spring", "Ring", etc.).		'''The type of the object''' (e.g. "Spring", "Ring", etc.).

Line 508:		Line 508:
	</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>		</syntaxhighlight>{{Notice\|type=note\|content=<b>Note that the following are not allowed to be used as custom property names:</b>

	• Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with HSON's position property).		• Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with [[HSON Format#3.6. position\|HSON's position property]]).
	• Empty strings		• Empty strings
	• Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:		• Strings which contain forward slashes.}}{{Notice\|type=info\|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:

PTKay at 11:03, 14 February 2025

2025-02-14T11:03:27Z

Show changes

PTKay at 10:59, 14 February 2025

2025-02-14T10:59:50Z

← Older revision		Revision as of 10:59, 14 February 2025
Line 32:		Line 32:
	The following is an example file in the HSON Format, which represents a "project" called "Sample Project" that contains 5 objects.		The following is an example file in the HSON Format, which represents a "project" called "Sample Project" that contains 5 objects.

	This example file will be referenced periodically throughout the format specification.<syntaxhighlight lang="json">		This example file will be referenced periodically throughout the [[HSON Format#Format Specification\|format specification]].<syntaxhighlight lang="json">
	{		{
	"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",		"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",
Line 172:		Line 172:

	<b>C#</b>:		<b>C#</b>:
	<~~pre~~>		<syntaxhighlight lang="c#">
	public static string GetRFC3339Time()		public static string GetRFC3339Time()
	{		{
Line 178:		Line 178:
	CultureInfo.InvariantCulture);		CultureInfo.InvariantCulture);
	}		}
	</~~pre~~>		</syntaxhighlight>
	<b>C++11</b>:		<b>C++11</b>:
	<~~pre~~>		<syntaxhighlight lang="c++">
	#include <string>		#include <string>
	#include <stdexcept>		#include <stdexcept>
Line 198:		Line 198:
	return std::string(buf, len);		return std::string(buf, len);
	}		}
	</~~pre~~>		</syntaxhighlight>
	<b>C</b>:		<b>C</b>:
	<~~pre~~>		<syntaxhighlight lang="c">
	#include <time.h>		#include <time.h>

Line 212:		Line 212:
	return strftime(buf, bufSize, "%FT%TZ", gmtime(&time));		return strftime(buf, bufSize, "%FT%TZ", gmtime(&time));
	}		}
	</~~pre~~>}}		</syntaxhighlight>}}

	==== 2.4. version ====		==== 2.4. version ====

PTKay at 10:57, 14 February 2025

2025-02-14T10:57:02Z

← Older revision		Revision as of 10:57, 14 February 2025
Line 14:		Line 14:
	To validate ''all'' .hson files against the schema in your editor of choice, refer to the instructions in the README from the above repository.		To validate ''all'' .hson files against the schema in your editor of choice, refer to the instructions in the README from the above repository.

	To manually validate against the schema on a per-file basis, include the following line at the top-level of your HSON file(s), before the HSON file format version parameter.<syntaxhighlight lang="json">		To manually validate against the schema on a per-file basis, include the following line at the top-level of your HSON file(s), before the HSON file format [[HSON Format#1. version\|version parameter]].<syntaxhighlight lang="json">
	"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",		"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",
	</syntaxhighlight>If writing tooling that generates HSON, consider having your tooling write this line to generated files.		</syntaxhighlight>If writing tooling that generates HSON, consider having your tooling write this line to generated files.
Line 23:		Line 23:
	=== C# ===		=== C# ===

	* '''libHSON:''' The official C# implementation of HSON. Allows for simple, efficient, feature-complete, two-way serialization of HSON data.		* '''[https://github.com/hedge-dev/libHSON-csharp libHSON]:''' The official C# implementation of HSON. Allows for simple, efficient, feature-complete, two-way serialization of HSON data.

	=== C++ ===		=== C++ ===

	* '''HedgeLib:''' Radfordhound's open-source library and collection of tools that aims to makes modding games in the Sonic the Hedgehog franchise easier. It contains a feature-complete two-way HSON implementation, which is used in its level-editing tooling.		* '''[https://github.com/Radfordhound/HedgeLib HedgeLib]:''' Radfordhound's open-source library and collection of tools that aims to makes modding games in the Sonic the Hedgehog franchise easier. It contains a feature-complete two-way HSON implementation, which is used in its level-editing tooling.

	== Example ==		== Example ==
Line 164:		Line 164:
	==== 2.3. date ====		==== 2.3. date ====
	{{Notice\|type=info\|content=• <b>Type</b>: string}}		{{Notice\|type=info\|content=• <b>Type</b>: string}}
	'''The date/time the project was created at''', represented as a string in the RFC 3339 format (a similar standard to ISO 8601).		'''The date/time the project was created at''', represented as a string in the [https://www.rfc-editor.org/rfc/rfc3339 RFC 3339 format] (a similar standard to ISO 8601).

	'''It is invalid to represent the date using any other format.'''		'''It is invalid to represent the date using any other format.'''
Line 287:		Line 287:
	==== 3.3. parentId ====		==== 3.3. parentId ====
	{{Notice\|type=info\|content=• <b>Type</b>: string}}		{{Notice\|type=info\|content=• <b>Type</b>: string}}
	'''The id of this object's parent object''', or a null UUID.		'''The [[HSON Format#3.1. id\|id]] of this object's parent object''', or a null UUID.

	If specified as a valid, non-null UUID, this object is a child of the object with the given UUID, meaning that the object's transform (represented via <code>position</code>, <code>rotation</code>, and <code>scale</code>) is relative to the parent's transform (which is relative to its parent's transform, and so on).		If specified as a valid, non-null UUID, this object is a child of the object with the given UUID, meaning that the object's transform (represented via <code>[[HSON Format#3.6. position\|position]]</code>, <code>[[HSON Format#3.7. rotation\|rotation]]</code>, and <code>[[HSON Format#3.8. scale\|scale]]</code>) is relative to the parent's transform (which is relative to its parent's transform, and so on).

	Otherwise, if it is not specified, or is specified as a null UUID, this object has no parent object, and the transform is global.		Otherwise, if it is not specified, or is specified as a null UUID, this object has no parent object, and the transform is global.
Line 326:		Line 326:
	==== 3.4. instanceOf ====		==== 3.4. instanceOf ====
	{{Notice\|type=info\|content=• <b>Type</b>: string}}		{{Notice\|type=info\|content=• <b>Type</b>: string}}
	'''The id of the object to be instanced''', or a null UUID.		'''The [[HSON Format#3.1. id\|id]] of the object to be instanced''', or a null UUID.

	If specified as a valid, non-null UUID, this object is an instance of the object with the given UUID, meaning that it will inherit '''ALL''' ''unspecified properties'' from the instanced object, '''with the notable exception of the <code>id</code> property''', instead of falling back to the usual defaults.		If specified as a valid, non-null UUID, this object is an instance of the object with the given UUID, meaning that it will inherit '''ALL''' ''unspecified properties'' from the instanced object, '''with the notable exception of the <code>[[HSON Format#3.1. id\|id]]</code> property''', instead of falling back to the usual defaults.

	Note that it will '''NOT''' affect the object's ''specified properties''; these will effectively "override" any properties taken from the instanced object.		Note that it will '''NOT''' affect the object's ''specified properties''; these will effectively "override" any properties taken from the instanced object.
Line 495:		Line 495:

	== Custom Properties ==		== Custom Properties ==
	In addition to all of the standard properties listed in the above specification, it is also completely valid to have your own custom properties which are not part of the specification, as demonstrated with the <code>myCustomEditor</code> and <code>myCustomValue</code> properties shown in the example file.		In addition to all of the standard properties listed in the above specification, it is also completely valid to have your own custom properties which are not part of the specification, as demonstrated with the <code>myCustomEditor</code> and <code>myCustomValue</code> properties shown in [[HSON Format#Example\|the example file]].

	If you use custom properties, it's highly recommended to place them in a property named after your tooling, as demonstrated with the <code>myCustomEditor</code> properties in the example.<syntaxhighlight lang="json">		If you use custom properties, it's highly recommended to place them in a property named after your tooling, as demonstrated with the <code>myCustomEditor</code> properties in the example.<syntaxhighlight lang="json">

PTKay: Created page with "'''The Hedgehog Set Object Notation Format''' ("HSON") is a custom JSON-based file format designed collaboratively by '''Darío''', '''Radfordhound''', '''ĐeäTh''', '''Skyth''', and '''Sajid''' to represent object placement in a "universal" (non-game/editor-specific) way. It was designed with the following principles in-mind: * '''Be universal.''' Specifically, it must be able to represent object placement data from ''at least'' any mainline 3D Sonic game in a non-ga..."

2025-02-14T10:51:03Z

Created page with "'''The Hedgehog Set Object Notation Format''' ("HSON") is a custom JSON-based file format designed collaboratively by '''Darío''', '''Radfordhound''', '''ĐeäTh''', '''Skyth''', and '''Sajid''' to represent object placement in a "universal" (non-game/editor-specific) way. It was designed with the following principles in-mind: * '''Be universal.''' Specifically, it must be able to represent object placement data from ''at least'' any mainline 3D Sonic game in a non-ga..."

New page

'''The Hedgehog Set Object Notation Format''' ("HSON") is a custom JSON-based file format designed collaboratively by '''Darío''', '''Radfordhound''', '''ĐeäTh''', '''Skyth''', and '''Sajid''' to represent object placement in a "universal" (non-game/editor-specific) way.

It was designed with the following principles in-mind:

* '''Be universal.''' Specifically, it must be able to represent object placement data from ''at least'' any mainline 3D Sonic game in a non-game/editor-specific way.
* '''Be simple.''' Specifically, it must not be difficult to parse and to generate.
* '''Be flexible.''' Specifically, it must be able to be adapted to do anything future games and tools may require.

== JSON Schema ==
The official JSON Schema for the HSON Format can be found at the [https://hedgedocs.com/docs/general/hson/ hson-schema GitHub repository].

It's useful (but not necessary) to validate .hson files against this schema in editors which support this feature, as doing so allows you to have autocompletion, descriptions of each property, and data validation.

To validate ''all'' .hson files against the schema in your editor of choice, refer to the instructions in the README from the above repository.

To manually validate against the schema on a per-file basis, include the following line at the top-level of your HSON file(s), before the HSON file format version parameter.<syntaxhighlight lang="json">
"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",
</syntaxhighlight>If writing tooling that generates HSON, consider having your tooling write this line to generated files.

== Implementations ==
As of the time of writing, the following known implementations exist:

=== C# ===

* '''libHSON:''' The official C# implementation of HSON. Allows for simple, efficient, feature-complete, two-way serialization of HSON data.

=== C++ ===

* '''HedgeLib:''' Radfordhound's open-source library and collection of tools that aims to makes modding games in the Sonic the Hedgehog franchise easier. It contains a feature-complete two-way HSON implementation, which is used in its level-editing tooling.

== Example ==
The following is an example file in the HSON Format, which represents a "project" called "Sample Project" that contains 5 objects.

This example file will be referenced periodically throughout the format specification.<syntaxhighlight lang="json">
{
"$schema": "https://raw.githubusercontent.com/hedge-dev/hson-schema/main/hson.schema.json",
"version": 1,
"metadata": {
"name": "Sample Project",
"author": "Takashi Iizuka, Morio Kishimoto",
"date": "2023-02-09T22:38:42Z",
"version": "1.0.0",
"description": "green hill is looking a lot more like sand hill rn",
"myCustomEditor": {
"viewportTabIndex": 0
}
},
"objects": [
{
"id": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}",
"name": "Spring #1",
"type": "Spring",
"position": [ 100.0, 0.0, 0.0 ],
"rotation": [ 0.0, 0.0, 0.0, 1.0 ],
"scale": [ 1.0, 1.0, 1.0 ],
"isEditorVisible": true,
"isExcluded": false,
"parameters": {
"tags": {
"RangeSpawning": {
"rangeIn": 100.0,
"rangeOut": 20.0
}
},
"visual": "Normal",
"firstSpeed": 420,
"outOfControl": 2.5,
"isHorming": true,
"actions": [
{
"action": "On",
"objectIds": [
"{2737e92f-4842-46cb-a590-e074f7b882f0}",
"{38285a58-9969-4c5f-a649-b91440962a71}"
],
"delayTime": 0.5
},
{
"action": "Off",
"objectIds": [],
"delayTime": 0.0
},
{
"action": "Off",
"objectIds": [],
"delayTime": 0.0
}
],
}
},
{
"type": "Ring"
},
{
"id": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"parentId": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}",
"type": "Ring",
"position": [ 0.0, 1.0, 0.0 ],
"parameters": {
"visibility": "Visible",
"respawnTime": 0.0
},
"myCustomValue": 893.5,
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
},
{
"id": "{38285a58-9969-4c5f-a649-b91440962a71}",
"instanceOf": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"position": [ 0.0, 2.0, 0.0 ],
"parameters": {
"respawnTime": 0.5
}
},
{
"id": "{81fdcaff-aa37-4c47-a665-5b6265a6b780}",
"parentId": "{00000000-0000-0000-0000-000000000000}",
"type": "DashPanel"
}
]
}
</syntaxhighlight>

== Format Specification ==
What follows is a specification of all standard properties supported by the HSON Format.
{{Notice|type=note|content=All of the following properties are OPTIONAL, unless otherwise specified.}}

=== 1. version ===
{{Notice|type=info|content=• Type: number
• Minimum: 1

This value is REQUIRED to be present in all HSON files.}}
'''The version of the HSON format being used by this file.''' It is represented as a number that is restricted in the following ways:

* It must have a zero fractional part (e.g. <code>1.5</code> would not be allowed, but <code>1.0</code> or <code>1</code> are).
* It must be greater than or equal to 1.

Because of these restrictions, it is valid for tooling to parse this value into an <code>unsigned int</code>.

Currently, version 1 is the latest version.

=== 2. metadata ===
{{Notice|type=info|content=• Type: object}}
'''Metadata for the project represented by this file.'''

It is intended to be used purely for tooling display purposes.

metadata is represented as a JSON <code>object</code> consisting of the following properties:

==== 2.1. name ====
{{Notice|type=info|content=• Type: string}}
'''The name of the project represented by this file.'''

==== 2.2. author ====
{{Notice|type=info|content=• Type: string}}
'''The author(s) of the project represented by this file.'''

If the project has multiple authors, we recommend writing each author's name with a comma and space separating them, like so:<syntaxhighlight lang="json">
"author": "Me, Myself, I"
</syntaxhighlight>

==== 2.3. date ====
{{Notice|type=info|content=• Type: string}}
'''The date/time the project was created at''', represented as a string in the RFC 3339 format (a similar standard to ISO 8601).

'''It is invalid to represent the date using any other format.'''

This limitation makes parsing dates in tooling a lot easier.
{{Notice|type=example|content=Feel free to copy-paste any of these code snippets and do what you want with them.

C#:
<pre>
public static string GetRFC3339Time()
{
return DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssK",
CultureInfo.InvariantCulture);
}
</pre>
C++11:
<pre>
#include <string>
#include <stdexcept>
#include <ctime>

std::string getRFC3339Time()
{
char buf[32]; // This is a few extra characters than should be necessary, just to be safe.
const auto time = std::time(nullptr);
const auto len = std::strftime(buf, sizeof(buf), "%FT%TZ", std::gmtime(&time));

if (!len)
{
throw std::runtime_error("Failed to get RFC 3339 format time");
}

return std::string(buf, len);
}
</pre>
C:
<pre>
#include <time.h>

/*
Returns 0 on failure, or the number of bytes written
into buf (not including the null terminator) on success.
*/
int getRFC3339Time(size_t bufSize, char* buf)
{
const time_t time = time(NULL);
return strftime(buf, bufSize, "%FT%TZ", gmtime(&time));
}
</pre>}}

==== 2.4. version ====
{{Notice|type=info|content=• Type: string}}
'''The version number of the project''', represented as a string.

How you want to version your project is up to you; these are all valid:<syntaxhighlight lang="json">
"version": "1.0.0"
"version": "1"
"version": "beta release"
</syntaxhighlight>'''Tooling should treat this as an arbitrary string in no particular format.'''

==== 2.5. description ====
{{Notice|type=info|content=• Type: string}}
'''The description of the project represented by this file.'''

=== 3. objects ===
{{Notice|type=info|content=• Type: array}}
'''An array containing all of the objects contained within the project.'''

Each object is represented as a JSON <code>object</code> consisting of the following properties:

==== 3.1. id ====
{{Notice|type=info|content=• Type: string}}
'''The UUID (aka GUID) of the object''', represented as a case-insensitive string formatted like this: <code>{11111111-2222-3333-4444-555555555555}</code>.

Note that it is enclosed in curly brackets; this is to make it clear that it is supposed to be parsed as a UUID, and '''NOT''' as a number.

The object's UUID is used to reference the object throughout the project.

It must be unique throughout the project; that is, '''no two objects within the same project are allowed to have the same UUID.''' That's what makes them ''UUIDs''.

It also '''cannot be set to the following value''': <code>{00000000-0000-0000-0000-000000000000}</code>, as this value is reserved for "null" object references.

This property can be omitted (leaving the object without a specified UUID) if the object never needs to be referenced. This helps to save some space.

Tools are free to generate their own UUIDs for objects without a specified UUID, or to just think of the object as not having a UUID. Whichever is more convenient.
{{Notice|type=example|content=Valid UUID (lowercase):
<pre>
"id": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}"
</pre>

Valid UUID (uppercase):
<pre>
"id": "{FD3E6BC9-5D2D-4DA8-A22D-F88E709B3E48}"
</pre>

Invalid UUID (no enclosing curly brackets):
<pre>
"id": "fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48"
</pre>

Invalid UUID (not a UUID):
<pre>
"id": "{2}"
</pre>
Invalid UUID (the special "null" UUID value is not valid to use as the object's id):
<pre>
"id": "{00000000-0000-0000-0000-000000000000}"
</pre>

Valid object references (the special "null" UUID value is valid to use in object references):
<pre>
"parentId": "{00000000-0000-0000-0000-000000000000}",
"instanceOf": "{00000000-0000-0000-0000-000000000000}"
</pre>}}

==== 3.2. name ====
{{Notice|type=info|content=• Type: string}}
'''The name of the object.''' This is an arbitrary string that can be anything you want.

It is intended to be used purely for tooling display purposes.

==== 3.3. parentId ====
{{Notice|type=info|content=• Type: string}}
'''The id of this object's parent object''', or a null UUID.

If specified as a valid, non-null UUID, this object is a child of the object with the given UUID, meaning that the object's transform (represented via <code>position</code>, <code>rotation</code>, and <code>scale</code>) is relative to the parent's transform (which is relative to its parent's transform, and so on).

Otherwise, if it is not specified, or is specified as a null UUID, this object has no parent object, and the transform is global.
{{Notice|type=example|content=<pre>
{
"id": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"parentId": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}",
"type": "Ring",
"position": [ 0.0, 1.0, 0.0 ],
"parameters": {
"visibility": "Visible",
"respawnTime": 0.0
},
"myCustomValue": 893.5,
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
}
</pre>

In this snippet from the example file, the object has specified a position of <code>[ 0.0, 1.0, 0.0 ]</code>, and a parentId of <code>{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}</code>, which means that its transform is local to the transform of the object which uses that UUID (not included in this snippet).

This parent object has a position of <code>[ 100.0, 0.0, 0.0 ]</code>.

So, the above object's global position is <code>[ 100.0, 1.0, 0.0 ]</code>.}}{{Notice|type=example|content=<pre>
{
"id": "{81fdcaff-aa37-4c47-a665-5b6265a6b780}",
"parentId": "{00000000-0000-0000-0000-000000000000}",
"type": "DashPanel"
}
</pre>

In this snippet from the example file, the object has specified a parentId of <code>{00000000-0000-0000-0000-000000000000}</code> (the special UUID null value), which is equivalent to not specifying a parentId. This means that this object has no parent.}}

==== 3.4. instanceOf ====
{{Notice|type=info|content=• Type: string}}
'''The id of the object to be instanced''', or a null UUID.

If specified as a valid, non-null UUID, this object is an instance of the object with the given UUID, meaning that it will inherit '''ALL''' ''unspecified properties'' from the instanced object, '''with the notable exception of the <code>id</code> property''', instead of falling back to the usual defaults.

Note that it will '''NOT''' affect the object's ''specified properties''; these will effectively "override" any properties taken from the instanced object.

Otherwise, if it is not specified, or is specified as a null UUID, this object is not an instance.
{{Notice|type=example|content=<pre>
{
"id": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"parentId": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}",
"type": "Ring",
"position": [ 0.0, 1.0, 0.0 ],
"parameters": {
"visibility": "Visible",
"respawnTime": 0.0
},
"myCustomValue": 893.5,
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
},
{
"id": "{38285a58-9969-4c5f-a649-b91440962a71}",
"instanceOf": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"position": [ 0.0, 2.0, 0.0 ],
"parameters": {
"respawnTime": 0.5
}
}
</pre>
In this snippet from the example file, the second listed object (UUID: <code>38285a58-9969-4c5f-a649-b91440962a71</code>) is an instance of the first listed object (UUID: <code>2737e92f-4842-46cb-a590-e074f7b882f0</code>).

As such, it will inherit all of the unspecified properties from the first object, including the <code>parentId</code>, <code>type</code>, <code>myCustomValue</code>, and <codemyCustomEditor</code> properties, as well as the visibility parameter.

It will NOT, however, inherit the specified properties, including the <code>id</code>, <code>instanceOf</code>, and <code>position</code> properties, as well as the <code>respawnTime</code> parameter.

This means that the second object in the above snippet will be equivalent to the following object:
<pre>
{
"id": "{38285a58-9969-4c5f-a649-b91440962a71}",
"parentId": "{fd3e6bc9-5d2d-4da8-a22d-f88e709b3e48}",
"type": "Ring",
"instanceOf": "{2737e92f-4842-46cb-a590-e074f7b882f0}",
"position": [ 0.0, 2.0, 0.0 ],
"parameters": {
"visibility": "Visible",
"respawnTime": 0.5
},
"myCustomValue": 893.5,
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
}
</pre>
As you can see, this is a simple, yet powerful system that allows for many possibilities.}}{{Notice|type=note|content=UUIDs have a special exception; they never get inherited from the instanced object.

For example:
<pre>
{
"id": "{AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA}",
"type": "Ring"
},
{
"instanceOf": "{AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA}"
}
</pre>
The second object listed in the above example will inherit all properties from the first object, except for the <code>id</code>.

This is due to the fact that every valid object must have its own unique UUID.}}

==== 3.5. type ====
{{Notice|type=info|content=• Type: string

This value is REQUIRED to be present, unless this object is an instance of another object, in which case, it is optional, as the type will just be taken from the instanced object.}}
'''The type of the object''' (e.g. "Spring", "Ring", etc.).

Note that this value is not game-specific and can be set to anything, with one exception: '''it is not valid for type to be an empty string'''.

==== 3.6. position ====
{{Notice|type=info|content=• Type: array
• Default: <code>[ 0.0, 0.0, 0.0 ]</code>}}
'''The position of the object within 3D space.''' Represented as a three-dimensional array of <code>number</code>s, representing a vector3 using Y-Up right-handed coordinates (X-right, Y-up, and Z-backwards), and meters as its units.

If this object is a child of another object, this position value is local to the transform of the parent object (which is local to the transform of its parent, and so on).

Otherwise, this position value is global.

If this property is not specified, the value <code>[ 0.0, 0.0, 0.0 ]</code> will be used as a fallback.

==== 3.7. rotation ====
{{Notice|type=info|content=• Type: array
• Default: <code>[ 0.0, 0.0, 0.0, 1.0 ]</code>}}
'''The rotation of the object within 3D space.''' Represented as a four-dimensional array of <code>number</code>s, representing a quaternion using Y-up right-handed coordinates.

If this object is a child of another object, this rotation value is local to the transform of the parent object (which is local to the transform of its parent, and so on).

Otherwise, this rotation value is global.

If this property is not specified, the value <code>[ 0.0, 0.0, 0.0, 1.0 ]</code> will be used as a fallback.
{{Notice|type=note|content=Rotation values must be represented as a four-dimensional array representing a quaternion.

It is not valid to represent rotation values using other methods, such as by using three-dimensional arrays representing euler angles or binary angle measurement (BAMS).

When dealing with formats that utilize these (or other) methods, tooling must convert to/from quaternions as necessary.}}

==== 3.8. scale ====
{{Notice|type=info|content=• Type: array
• Default: <code>[ 1.0, 1.0, 1.0 ]</code>}}
'''The scale of the object within 3D space.''' Represented as a three-dimensional array of <code>number</code>s, representing a vector3 using Y-up right-handed coordinates (X-right, Y-up, and Z-backwards), and meters as its units.

If this object is a child of another object, this scale value is local to the transform of the parent object (which is local to the transform of its parent, and so on).

Otherwise, this scale value is global.

If this property is not specified, the value <code>[ 1.0, 1.0, 1.0 ]</code> will be used as a fallback.

==== 3.9. isEditorVisible ====
{{Notice|type=info|content=• Type: boolean
• Default: <code>true</code>}}
'''Whether the object should be visible in the editor's 3D display''' (as applicable). Note that this is purely for editors, and has no effect on whether the object is visible in-game.

When converting from HSON to game-specific file(s), tooling should ignore this value.

If this property is not specified, the value <code>true</code> will be used as a fallback.

==== 3.10. isExcluded ====
{{Notice|type=info|content=• Type: boolean
• Default: <code>false</code>}}
'''Whether the object should be excluded from game data.'''

If specified as <code>true</code>, editors should (as applicable) hide the object from 3D display, but still show it in the object hierarchy as a disabled object, and provide a mechanism for users to un-exclude it.

When converting from HSON to a game format, tooling should treat excluded objects as if they do not exist, by simply not writing them to the resulting game-specific file(s).

If this property is not specified, the value <code>false</code> will be used as a fallback.

==== 3.11. parameters ====
{{Notice|type=info|content=• Type: object}}
'''All named parameters specific to this object type and/or game.''' For example, the <code>firstSpeed</code> parameter for objects of the <code>Spring</code> type in Sonic Frontiers, which specifies the speed the object will launch the player off with.

This is the place to put all parameters that are specific to objects of the specified <code>type</code>. It's also a great place to put game-specific parameters, such as object visibility ranges.

Any number of properties of any JSON type are allowed here, all of which are always entirely optional.

Tooling should treat this as an arbitrary list of key-value pairs, and provide some mechanism that allows the user to modify '''ALL''' of them as they please. It does not, however, have to provide a mechanism to add, remove, or edit the type of these parameters, as this may be undesirable depending on your use-case.

Tooling should not require any of these parameters to be present. When converting, tooling should, instead, lookup each parameter by its name as needed, and either error-out or fallback to a default value if a required parameter is not present.
{{Notice|type=note|content=Note that the following are not allowed to be used as parameter names:

• Empty strings.
• Strings which contain forward slashes.}}{{Notice|type=info|content=The "no forward slash" rule allows tooling to access parameters by "path", like so:
<pre>
"parameters": {
"tags": {
"RangeSpawning": {
"rangeIn": 100.0,
"rangeOut": 20.0
}
}
}
</pre>

• <code>"tags/RangeSpawning/rangeIn": 100.0</code>
• <code>"tags/RangeSpawning/rangeIn": 20.0</code>}}

== Custom Properties ==
In addition to all of the standard properties listed in the above specification, it is also completely valid to have your own custom properties which are not part of the specification, as demonstrated with the <code>myCustomEditor</code> and <code>myCustomValue</code> properties shown in the example file.

If you use custom properties, it's highly recommended to place them in a property named after your tooling, as demonstrated with the <code>myCustomEditor</code> properties in the example.<syntaxhighlight lang="json">
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
</syntaxhighlight>Doing this helps to reduce potential name collisions with custom properties from other tools, which might end up sharing the same name(s).

If your custom property is intended to be used across multiple tools (e.g. an unofficial "extension" to the HSON format), then it's recommended to ignore the above advice and just use the custom property directly instead, as demonstrated with the <code>myCustomValue</code> property in the example.<syntaxhighlight lang="json">
"myCustomValue": 893.5,
</syntaxhighlight>{{Notice|type=note|content=Note that the following are not allowed to be used as custom property names:

• Names which directly collide with properties that are part of the HSON specification (e.g. you can have a custom property called "position", but it has to be placed such that it does not collide with HSON's position property).
• Empty strings
• Strings which contain forward slashes.}}{{Notice|type=info|content=The "no forward slash" rule allows tooling to access custom properties by "path", like so:
<pre>
"myCustomEditor": {
"presetPlacementType": "LINE",
"presetPlacementDistance": 1.0
}
</pre>

• <code>"myCustomEditor/presetPlacementType": "LINE"</code>
• <code>"myCustomEditor/presetPlacementDistance": 1.0</code>}}