GrinderKit is a demo engine inside the verso-3d library that provides you ways to compose, parametrisize, time and run several effects in a timeline. Concept is quite similar to how video editing software work, except that each block in the timeline is chosen to be certain effect which in turn then defined what will be rendered. In GrinderKit these block are called DemoParts.
A demo can be defined in a JSON based custom format which is be presented in this document. You can use built-in DemoParts or use C++ code to create your own custom effects.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "format": |
Format version number to future proofing. Type: string required Supported values: "GrinderKit01" |
||||||
| "name": |
Name of the demo. Type: string required Example: "Enlil, king of all the lands, father of all the gods" |
||||||
| "version": |
Free-form text version name for the demo. Type: string required Example: "2018/05/02 some identification" |
||||||
| "authors": |
Free-form list of authors. Type: string required Example: "codise / dahlia" |
||||||
| "paths": { |
Object containing the paths to data files. Type: object optional |
||||||
| "models": |
Directory path to where the 3D objects will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "models" |
||||||
| "shaders": |
Directory path to where the shader sources will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "shaders" |
||||||
| "material": |
Directory path to where the material shader sources will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "shaders/material" |
||||||
| "music": |
Directory path to where the music will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "music" |
||||||
| "textures": |
Directory path to where the textures will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "textures" |
||||||
| "fonts": |
Directory path to where the fonts will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "fonts" |
||||||
| "particles": |
Directory path to where the particle textures will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "particles" |
||||||
| "gui": |
Directory path to where the gui textures will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "gui" |
||||||
| "guiIcons": |
Directory path to where the gui icons will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "gui/icons" |
||||||
| "guiStyles": |
Directory path to where the gui styles will be loaded relative to GrinderKit JSON file path. Type: string optional Default: "gui/styles" |
||||||
| }, | |||||||
| "music": |
Music file to play. Relative to "paths.music" directory. Type: string optional Example: "soundtrack.mp3" Supported formats: MP3/MP2/MP1/OGG/WAV/AIFF |
||||||
| "muted": |
If the music should be muted. Type: boolean optional Supported values: true | falsedefault |
||||||
| "targetFps": |
FPS which the demo will try to match. Note that if VSync is on then that limit won't be surpassed. Type: number optional Default: 60 |
||||||
| "playmode": |
Mode which the demo player uses after starting. "Production" shows the demo normally. "Development" open up development mode. Type: PlayMode optional Supported values: "Production"default | "Development" |
||||||
| "debugPlaybackRangeStart": |
Debug playback range start seconds. For development purposes to automatically skip the the defined debug playback range. Type: seconds optional Default: 0 |
||||||
| "debugPlaybackRangeEnd": |
Debug playback range end seconds. For development purposes to automatically skip the the defined debug playback range. Type: seconds optional Default: 0 |
||||||
| "loop": |
If demo playback should be looped. This will be probably removed in the future as it exists in the setup dialog / command line parameters also. Type: boolean optional Supported values: true | falsedefault |
||||||
| "duration": |
How many seconds the demo will last. Note that currently is the music is shorter then it will loop again from the beginning. Type: seconds optional Default: 180 |
||||||
| "demoparts": [ |
Array of demo parts. Type: array of demopart objects required |
||||||
| ] | |||||||
| } | |||||||
| { | |||||||
|---|---|---|---|---|---|---|---|
| "name": |
Name of the demopart. Type: string required Example: "Good is thy riddle, Gestumblindi" |
||||||
| "type": |
Type of demopart object. Defines which code the engine will execute for this demopart and whichs params will it parse. Type: string required Supported values: "verso.clearscreen" | "verso.heightmap" | "verso.imageviewer" | "verso.imguitest" | "verso.particles" | "verso.randombackground" | "verso.scenegraph" | "verso.shadertoy" | "verso.verso-3dtest" |
||||||
| "start": |
Time in seconds when the demopart will start playing. Type: seconds required Example: 2.52 |
||||||
| "duration": |
How many seconds the demopart will last. Note that playback will be capped to global duration even if there are demoparts longer than it. Type: seconds required Example: 12.45 |
||||||
| "priority": |
Render priority. When there are several demoparts active at the same time the demopart with bigger priority will be rendered after the demopart with the lower priority. Type: integer number required Example: 3 |
||||||
| "params": { |
Object containing custom parameters for the chosen demopart type. Even is demopart doesn't take any parameters you must at least define an empty object, e.g. "params": {} Type: object required |
||||||
| } | |||||||
| } | |||||||
ClearScreen clears the screen color and/or depth buffer.
| { ..., "type": "verso.clearscreen", ..., "params": { | |||||||
|---|---|---|---|---|---|---|---|
| "clear": { |
Set how to clear the screen. Type: ClearParamoptional Default: Clear screen with "SolidColor" and color [ 0.2235, 0.2235, 0.2235 ]. |
||||||
| }, | |||||||
| } | |||||||
{ "name": "Clear", "type": "verso.clearscreen",
"start": 0, "duration": 3000, "priority": 0, "params": {
}},
{ "name": "Clear", "type": "verso.clearscreen",
"start": 0, "duration": 3000, "priority": 0, "params": {
"clear": {
"color": [1, 0, 1]
}
}},
{ "name": "Clear", "type": "verso.clearscreen",
"start": 0, "duration": 3000, "priority": 0, "params": {
"clear": {
"color": [1, 0, 1],
"clearFlag": "ColorBuffer"
}
}},
| { | |||||||
|---|---|---|---|---|---|---|---|
| } |
ImageViewer show a given image on the screen and optionally clears the screen.
| { ..., "type": "verso.imageviewer", ..., "params": { | |||||||
|---|---|---|---|---|---|---|---|
| "source": |
Image file name to show. Relative to "paths.textures" directory. Type: string required Example: "goonies.png" Supported file extensions: .jpg | .jpeg | .png | .tga | .bmp | .psd | .gif | .hdr | .pic | .pnm |
||||||
| "clear": { |
Set how to clear the screen. Type: ClearParamoptional Default: Do not clear the screen. |
||||||
| }, | |||||||
| "align": { |
Align the image on the screen. "Undefined" means that image won't be aligned on that axis. Type: Alignoptional Default: { "horizontal": "Undefined", "vertical": "Undefined" } |
||||||
| }, | |||||||
| "relative": |
Translate and/or scale the image relative to screen width and height. For translation: Top-Left = (0.0, 0.0), Bottom-right = (1.0, 1.0) For scaling: 0.0=zero size 1.0=full screen width/height. Type: Rectfoptional Default: { "x": 0, "y": 0, "width": 0, "height": 0 } |
||||||
| "aspectRatioFix": |
If true then use image aspect ratio when scaling. Type: boolean optional Default: true |
||||||
| "rotation": |
Rotate the image in given angle in degrees. Type: number optional Default: 0.0 |
||||||
| "blend": |
Which BlendMode to use for rendering the image. Type: BlendMode optional Default: "Transcluent" |
||||||
| "alpha": |
Global alpha value for the image which is multiplied with the image pixels' alpha values. Note that the effect requires a suitable BlendMode to be set. Value is between [0.0..1.0]. 0.0 = fully transparent, 1.0 = fully visible. Type: number optional Default: 1.0 |
||||||
| "minfilter": |
Which minification filter to use when scaling the image down from it's original resolution. Type: MinFilter optional Default: "Linear" |
||||||
| "magfilter": |
Which magnication filter to use when scaling the image up from it's original resolution. Type: MagFilter optional Default: "Linear" |
||||||
| } | |||||||
{ "name": "My image", "type": "verso.imageviewer",
"start": 0, "duration": 3000, "priority": 0, "params": {
"source": "quote.png"
}},
{ "name": "aciid1", "type": "verso.imageviewer",
"start": 0, "duration": 3000, "priority": 0, "params": {
"source": "acid.png",
"align": {
"horizontal": "Right",
"vertical": "Bottom"
},
"relative": {
"height": 0.1
},
"aspectRatioFix": true,
"rotation": 45,
"blend": "Transcluent",
"alpha": 0.25,
"magfilter": "Nearest"
}},
{ "name": "aciid2", "type": "verso.imageviewer",
"start": 0, "duration": 3000, "priority": 0, "params": {
"clear": {
"color": [0.45, 0.56, 0.60, 1],
"clearFlag": "SolidColor"
},
"source": "acid.png",
"align": {
"horizontal": "Left",
"vertical": "Top"
},
"relative": {
"x": 0.1,
"y": 0.01,
"width": 0.4
},
"rotation": 210,
"blend": "Transcluent",
"alpha": 0.7
}},
| { | |||||||
|---|---|---|---|---|---|---|---|
| } |
| { | |||||||
|---|---|---|---|---|---|---|---|
| "particles": { |
Defines a particle system. Type: ParticlesParamrequired |
||||||
| }, | |||||||
| "behaviour": { |
Defines how particles react when time goes on. Type: BehaviourParamrequired |
||||||
| }, | |||||||
| "emitter": { |
Defines what kind of particles are emitted. Type: EmitterParamrequired |
||||||
| }, | |||||||
| "sequencer": { |
Defines when and how many particles are emitted. Type: SequencerParamrequired |
||||||
| }, | |||||||
| } | |||||||
| { | |||||||
|---|---|---|---|---|---|---|---|
| "sourcePath": |
Directory path where a random image is chosen during load. Relative to "paths.textures" directory. Type: string optional Default: "paths.textures" directory Example: "some/directory" Supported file extensions: .jpg | .jpeg | .png | .tga | .bmp | .psd | .gif | .hdr | .pic | .pnm |
||||||
| "clear": { |
Set how to clear the screen. Type: ClearParamoptional Default: Clear screen with "SolidColor" and color [ 0.2235, 0.2235, 0.2235 ]. |
||||||
| }, | |||||||
| } | |||||||
Clear screen with default color and show random background from backgrounds directory relative to "paths.textures" directory.
{ "name": "My image", "type": "verso.randombackground",
"start": 0, "duration": 3000, "priority": 0, "params": {
"sourcePath": "backgrounds"
}},
Clear screen with color [ 1, 0.5, 0.5 ] and show random background from backgrounds directory relative to "paths.textures" directory.
{ "name": "My image", "type": "verso.randombackground",
"start": 0, "duration": 3000, "priority": 0, "params": {
"sourcePath": "backgrounds",
"clear": {
"color": [ 1, 0.5, 0.5 ]
}
}},
| { | |||||||
|---|---|---|---|---|---|---|---|
| } |
| { | |||||||
|---|---|---|---|---|---|---|---|
| "shader": { |
Set shadertoy compatible shader to use. Type: ShaderParamoptional Default: { "frag": "shadertoy/shadertoy.default.330.frag", "vert": "shadertoy/shadertoy.default.330.vert" } |
||||||
| }, | |||||||
| "channel": { |
Set shadertoy channels. List of file names to textures relative to "paths.textures" directory. Type: ChannelParamoptional Default: [] Supported file extensions: .jpg | .jpeg | .png | .tga | .bmp | .psd | .gif | .hdr | .pic | .pnm | animation TODO | video files TODO |
||||||
| } | |||||||
| } | |||||||
Shows a Shadertoy converted simple vortex effect.
{ "name": "2d vortex effect test", "type": "verso.shadertoy",
"start": 0, "duration": 3000, "priority": 0, "params": {
"shader": { "frag": "shadertoy/external/simple_vortex_effect_2d_by_public_int_i.frag" },
"channel": [ "shadertoy/tex07.jpg", "shadertoy/tex07.jpg" ] }}
}},
Shows a Shadertoy converted simple eye blower effect.
{ "name": "Interference shader test", "type": "verso.shadertoy",
"start": 0, "duration": 3000, "priority": 0, "params": {
"shader": { "frag": "shadertoy/external/simple_eye_blower_by_lanza.frag" }
}},
| { | |||||||
|---|---|---|---|---|---|---|---|
| } |
|
null is a JSON basic type which indicates that value does not exist, is unset or empty. Type: null Supported values: null |
|
object is a JSON basic type which consists of any number of fields inside curly brackets. Type: object Examples: {} | { "some field": "some value" } | { "some field": "some value", "another field": 100 } |
|
array is a JSON basic type which consists of zero or more values inside square brackets. Type: array Examples: [] | ["first", "second"] | [1.0, 2, 3.5] |
|
boolean is a JSON basic type which is either true or false. Type: boolean Supported values: true | false |
|
number is a JSON basic type which can be any number. Type: number Examples: 0 | -5 | 5.0 | 0.2452 |
|
integer isn't a JSON basic type but a custom type in GrinderKit for values that cannot contain decimals. If decimals are given to an integer value then they're floored (removed) and warning is printed out. Type: integer Examples: 0 | -5 | 5.0 | 0.9222 (will be floored to 0 with a warning) |
|
string is a JSON basic type which is sequence of zero or more characters inside double quotation marks. Type: string Examples: "" | "asdf" | "Some words..." |
|
Align defines how something should be aligned. It's an object containing two fields: "horizontal"optional and "vertical"optional. Type: object Possible values for "horizontal": "Left" | "Center" | "Right" | "Undefined" Possible values for "vertical": "Top" | "Center" | "Bottom" | "Undefined" Examples: {} | {"horizontal": "Center"} | {"horizontal": "Left", "vertical": "Bottom"} |
|
Color defines a RGB or RGBA color. It's an array containing 3-4 number values between 0 and 1. For color components 1 means full color and zero no color, for alpha 0 means full transparency and 1 no transparency. TODO: support for "#rrggbbaa" values. Type: array of 3 or 4 numbers Examples: [0, 1, 0] | [0.52, 0, 0.62, 0.5] |
|
Rangef defines a range of numbers between given a and b inside an array. Type: array of two numbers Examples: [0, 2] | [-5.2, 25.9] |
|
Rectf defines a rectangle. It's and object containing four number fields: "x"optional, "y"optional, "width"optional and "height"optional. "x" and "y" defines the top-left point for the rectangle and "width" and "height" the size. TODO: add support for array of four values. Type: object Examples: {} | {"x": 1.5, "y": 2, "width": 5, "height": 10} |
|
Vector2f defines a two-dimensional vector. It's and object containing two number fields: "x"optional, "y"optional. "x" and "y" defines the point for the vector. This can be used depending on the context as a (x,y) position in space or a direction from origo (0,0) to (x,y). TODO: add support for array of two values. Type: object Examples: {} | {"x": 1.5, "y": 2} |
|
Vector2i defines a two-dimensional vector. It's and object containing two integer numbers fields: "x"optional, "y"optional. "x" and "y" defines the point for the vector. This can be used depending on the context as a (x,y) position in space or a direction from origo (0,0) to (x,y). TODO: add support for array of two values. Type: object Examples: {} | {"x": 1, "y": 2} | {"x": 1.9, "y": -2.2} (will be floored to (1, -2 with a warning)) |
|
Vector3f defines a three-dimensional vector. It's and object containing three number fields: "x"optional, "y"optional, "z"optional. "x", "y" and "z" defines the point for the vector. This can be used depending on the context as a (x,y,z) position in space or a direction from origo (0,0) to (x,y,z). TODO: add support for array of three values. Type: object Examples: {} | {"x": 1.5, "y": 2, "y": -3} |
|
BlendMode defines which blend mode to use for rendering. Type: string Supported values:
|
|
ClearFlag defines the way screen should be cleared. Type: string Supported values:
|
|
MinFilter defines how texture is scaled down. The texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. Type: string Supported values:
|
|
MagFilter defines how texture is scaled up. The texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. Type: string Supported values:
|
|
Playmode is a enum like string with two possible values. Type: string Supported values: "Production" | "Development" |
|
TODO Type: TODO Supported values: TODO |
Defines how particles react when time goes on.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": |
Choose the type of behaviour to use. Type: string required |
||||||
| "..." |
Other parameters are dependent on the type. |
||||||
| } | |||||||
SimpleGravity defines a behaviour which applied a simple gravity to particles.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": | "SimpleGravity" | ||||||
| "TODO" | TODO | ||||||
| } | |||||||
|
ChannelParam is a list of channel texture file names in defined order. Type: array |
|
ClearParam defines how the screen should be cleared. It is an object with two fields "clearFlag"optional and "color"optional. Type: object |
Defines what kind of particles are emitted.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": |
Choose the type of emitter to use. Type: string required |
||||||
| "..." |
Other parameters are dependent on the type. |
||||||
| } | |||||||
SimpleRandom defines a emitter which emits random particles which ranges between values.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": | "SimpleRandom" | ||||||
| "TODO" | TODO | ||||||
| } | |||||||
SphericalRandom defines a emitter which emits particles on a randomly on a sphere.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": | "SphericalRandom" | ||||||
| "TODO" | TODO | ||||||
| } | |||||||
|
TODO Type: TODO Supported values: TODO |
Defines a particle system.
|
asd Type: TODO Supported values: TODO |
|
TODO Type: TODO Supported values: TODO |
Defines when and how many particles are emitted.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": |
Choose the type of sequencer to use. Type: string required |
||||||
| "..." |
Other parameters are dependent on the type. |
||||||
| } | |||||||
BurstInterval defines a sequencer which supports optional initial burst of particles, optional continous burst of particles every n seconds and optional constant rate of particles per second.
| { | |||||||
|---|---|---|---|---|---|---|---|
| "type": | "BurstInterval" | ||||||
| "TODO" | TODO | ||||||
| } | |||||||
| { | |||||||
|---|---|---|---|---|---|---|---|
| "frag": |
Fragment shader file name to use. Relative to "paths.shaders" directory. Type: string optional Example: "normalvisualizer3d.330.frag" Support: Shader sources should be GLSL and OpenGL 3.3 compatible. |
||||||
| "vert": |
Vertex shader file name to use. Relative to "paths.shaders" directory. Type: string optional Example: "normalvisualizer3d.330.vert" |
||||||
| "geom": |
Geometry shader file name to use. Relative to "paths.shaders" directory. Type: string optional Example: "normalvisualizer3d.330.geom" |
||||||
| } | |||||||
{
"format": "GrinderKit01",
"name": "Enlil, king of all the lands, father of all the gods",
"version": "2018/05/02 fix",
"authors": "Melem-Kish",
"paths": {
"models": "models",
"shaders": "shaders",
"material": "shaders/material",
"music": "music",
"textures": "textures",
"fonts": "fonts",
"particles": "particles",
"gui": "gui",
"guiIcons": "gui/icons",
"guiStyles": "gui/styles"
},
"music": "soundtrack.mp3",
"muted": true,
"targetFps": 60,
"playmode": "Development",
"duration": 123,
"loop": true,
"demoparts" : [
{ "name": "Clear", "type": "verso.clearscreen",
"start": 0, "duration": 3000, "priority": 0, "params": {
}},
{ "name": "Particles", "type": "verso.particles",
"start": 0, "duration": 123, "priority": 1, "params": {
"particles": {
"texture": "spacemist.png",
"blend": "Additive",
"position": [ 0.0, 0.0, 0.0 ],
"trailSaveInterval": 0.2,
"particleLimit": 1000,
"trailSize": 100
},
"behaviour": {
"type": "SimpleGravity",
"gravity": 9.81
},
"emitter": {
"type": "SphericalRandom",
"radius": [5.0, 10.0],
"x": 1,
"y": 1,
"z": 1,
"angle": 1,
"angleVelocity": 1,
"startSize": 1,
"endSize": 1,
"totalLifeTime": 1,
"red": 1,
"green": 1,
"blue": 1,
"startAlpha": 1,
"endAlpha": 1
},
"sequencer": {
"type": "BurstInterval"
}
}
},
{ "name": "Particles", "type": "verso.particles",
"start": 10, "duration": 123, "priority": 1, "params": {
"particles": {
"texture": "explosion.png"
},
"behaviour": {
"type": "SimpleGravity"
},
"emitter": {
"type": "SimpleRandom",
"xVelocity": 1,
"yVelocity": 1,
"zVelocity": 1
},
"sequencer": {
"type": "BurstInterval"
}
}
}
]
}