All of the file is meant to be case insensitive.
Contents |
The basic action looks like:
At [time] [command] [duration]
Which executes the given command, at the given time for the given duration.
Times can be absolute times, like 15s, or a previously defined time
Times are defined by
Define Time [time] "Name"
Where time is an absolute time, and "Name" (with quotes) is the name to be given to refer to from then on.
Time can be given in seconds (s), minutes (m), milliseconds (ms), hours (h)
For Example
15h3m19s21ms
Duration can be relative or absolute.
In 15s
or
Until 15s
"In" has the action that is occuring take 15s regardless of when the action is run.
"Until" will run the timer until the movie has been running for 15 seconds. It can also take in a previously defined time. This can be used to define important times and have things work, even if those event need to be changed later.
Commands are used to effect change in the movie.
Some commands affect which sprites are on the screen. These are:
Other commands affect the properties of sprites:
There are also commands that effect text. These are discussed in the Text section.
It should be noted that there is no guarantee which order the commands for a given time will be executed.
For example, if the following two statement are given:
At 15s Set "John" x=32 y=32 At 15s Set "John" x=15
There is no way to tell if John will end up with an x position of 32 or 15. The commands at a given time can be executed at any order the viewer feels like executing them.
On the other hand
At 15s Set "John" x=32 y=32 At 15s1ms Set "John" x=15
Will always execute the first one before the second. John will end up at 15.
Things can be defined
These are the things that are drawn. Without these, we are useless.
Define Sprite "Sprite" {
Load SVG "Filename"
}
This is the base sprite. All sprites come from SVG.
Spite can then be defined from other sprites.
Define Sprite "Sprite2" {
Use Sprite "Sprite" "SpriteName"
}
This would use a previously defined Sprite in this sprite, called SpriteName.
Sprites can also be defined in an external file. They are then loaded with:
Load Sprite "Filename" "SpriteName"
This is not done within a sprite. It is the same as defining the sprite. To use the sprite later, you would use it the same as if you had defined the sprite yourself.
Sprites can either load an SVG file, or group other sprites together. You can't load a sprite and Use a predefined sprite in the same definition.
Within a sprite definition, Set commands can be used without a time to set default parameters. For instance:
Define Sprite "Bob" {
Use Sprite "Bob_Forearm" "Forearm"
Set "Forearm" x=32 y=15 angle=13
}
Also, by default all used sprites are drawn. This can be changed by the inclusion of "Erase" commands. It is recommended to not use "Delete" commands inside a sprite definition. That'd be dumb. This allows you to load 3 different head sprites, one for each state, and then make 2 of them not drawn, and switch them out as needed.
Every sprite has a number of properties that describe it.
Examples of these might be:
All of these parameters are relative. This means if a sprite has an alpha of 50, but it's inside a sprite with an alpha of 50, then the first sprite's absolute alpha is 25 when it is drawn. Sprites are completely isolated from everything above them, always.
That being said, it might be useful to have some absolute positions. For instance, there was discussion about an object that emits particles. These particles should involve absolute position, so that if the emitter moves, the particles don't get dragged with it. This can be in version 2, maybe.
Within a Sprite Definition you can define actions. Actions are groups of events with a time relative to when they are called.
Define Sprite "Sprite" {
Use Sprite "Square" "Body"
Use Sprite "Line" "Arm"
Define Action "Walk" {
At 0 Change "Arm" angle=52 In 32s
At 32 Change "Arm" angle=0 In 5s
}
}
Will define an action called Walk to the sprite that moves the arm.
There are a few properties of actions that can be set either in it's definition or when its called. The parameters set when the action is called override all parameters given when the action is defined.
These are defined as follows
Define Action "Name" [properties] {
...
}
To aid with the animation of sprites, different components of sprites can be linked together. This creates a dependent part and an independent part.
It is similar to nesting, except all sprites are in one definition.
The command is used as follows
Map "DependentSprite" "ExportedPoint" To "IndependentSprite" "ExportedPoint"
The dependent sprite and the independent sprite are then attached at those points. This renders the position of the sprite's disabled. Rotation is still used frequently though.
For example, if you wanted to create an arm in a person sprite, you might do the following:
Use Sprite "Body_Forearm" "Forarm" Use Sprite "Body_Upperarm" "Upperarm" Use Sprite "Body_Hand" "Hand" Map "Hand" "Wrist" To "Forarm" "Wrist" Map "Forarm" "Elbow" To "Upperarm" "Elbow"
This will attach hand's exported point "Wrist" to the exported point "Wrist" on the forarm. They don't need to have the same name, but it's probably likely that they will.
At this point, any time the upper arm sprite is moved, the other sprites will move too. If the forarm is rotated, it will rotate around its dependent joint. This will move the hand as well. Etc.
Multiple objects can be mapped to a single independent joint, but a sprite can only ever directly depend on one point. For example, we could multiple feathers on the end of a feather duster, all mapped to the same point, but the feather duster can only be connected to one point on the hand.
If objects are to be broken away from a group, the following command is used
Unmap "DependentSprite" From "IndependentSprite"
In the feather duster example used above, you would use:
Unmap "Feather13" From "FeatherConnecter"
To remove Feather13 from the duster, perhaps to have it float down to the ground.
While defining a sprite, you can use the command
Export "Name" [x,y]
to export the given point under that name. This allows that point to be mapped to.
As kind of an idea, we could define a standard set of connections to be implemented by certain things. Like, all objects that could be picked up could have a "Hold" point that is meant to map to a hand.
Text rendering is by controlled by the viewer.
If the viewer chooses to render the text in a speech bubble, or some other form that needs to be connected to a point it needs to know where to connect the bubble to.
This is where the TalkPoint comes in. This can be either a position of the form [x,y] which maps to a point in this sprite, or the name of a sprite within this sprite.
This allows the sprite to pass off the talk point to another sprite. For instance, the John sprite could pass the TalkPoint to his head sprite, and his head sprite could pass the TalkPoint to the mouth sprite which then has some point. This means that if later, the mouth is switched out for something weird, or the head becomes a duck's head or something, John's TalkPoint doesn't have to change.
Sprites' names can include any character except "."
This is because, like OOP, the "." character is used to signify nesting. So, in any of the points thus far where a Sprite name is used, "Bob.Head.Eye" is just as acceptable.
Sprites should be named something useful to the audience, not a cryptic internal name. The reason is because if the Caption text theme or anything like that is used, then the name of the sprite is printed out. This means that it is preferable to name a sprite "Bob's Cat" rather than "BC" or something, because any text attached to that sprite will read "Bob's Cat: Text Text Text" or something.
In the case of nested names, it might be up to the viewer to decide what to do. Perhaps it could use the first and last name, so in the above example, the text caption might read "Bob's Eye" or something.
Text rendering in this is controlled by the viewer. All this file does is present text for the viewer to handle at certain times, and perhaps suggest some properties.
This also allows the viewer to run the text through a text to speech thing or put it through some other kind of accessibility device.
Text is drawn by calling the text command
Text "Text" [properties]
Which will draw the text with the given set of properties.
The following properties are supported by text:
Understand that none of these are guarantees. The viewer might not pay attention to any of the properties suggested by your text command.
Some examples of text rendering themes a viewer might support that the group has come up with are:
Actions, as described above, are collections of commands that are run. This allows you to have a number of pre-made combinations of actions that operate on the sprites.
The basic command for calling actions is
Call "Sprite" "Action" [parameters] [duration]
Which runs the given action. All of the times in the action are relative to the point in time the action is called.
The parameters given in the definition override any default parameters given in the action definition, stated above.
Be aware that unless the action has the "recursive" parameter off, either by default or in the call, the action will be also be called on all sub sprites.
The duration is optional. If the Action repeats, then the duration controls how long it will repeat for. If the action does not repeat, then the action is scaled to occur in this given amount of time. If the action is repeated and no duration is given, the action repeats until the sprite is erased. If the sprite doesn't repeat and no duration is given, the action will take the default amount of time.
The command
Scene "Name"
At a specified time will set the viewer to change scenes.
Scenes always run first of all commands at their specified time.
At the end of a scene, sprites are erased from the screen and all current actions are therefore ceased. At this point, it's just as though a new movie has started, from the movie's point of view. This could allow the viewer to jump to a scene, and start from there.
It also allows the author to be guaranteed of a blank slate. If they want a change of location, they don't have to manually keep track of and remove all sprites relating to the current environment, they just have to start a new scene.
At a certain time, you can also use
Load Scene "filename"
To import and play a scene from an external source. In the loading file, the scene can be seen as being one second long.
For example:
At 10s Load Scene "Other" At 11s Draw Sprite "Blob" "Hello"
will execute the scene in the file Other, and no matter how long the scene is, the sprite Blob will be draw right after the scene ends.
There are a number of properties of sprites that use coordinates. If writing a file, the coordinate system is defined by the file.
The very first line of a file containing commands must be a scene command, directly after that should be the lines of the file that set some parameters for the viewer. The viewer can be referred to as sprite name "."
This sprite supports some different options from other sprites.
Most of these options need to be set before any other sprites can be defined, and many of them probably can't be changed once set.
Initial parameters should not be given a time. This is because the order of execution can't be guaranteed. For example:
At 0 Set "." size=[100,100] At 0 Draw Sprite "Body" "George" pos=[20,20]
Could fail because the second line might be executed before the first.
Instead use
Set "." size=[100,100] At 0 Draw Sprite "Body" "George" pos=[20,20]
This is the only time commands without times can be used in the main part of the file. Only the viewer parameters can be set this way.
If you wanted to change something later, like the TextTheme, this needs a time.
At 15s Set "." TextTheme="SpeechBubble","Caption"
Anything following a "#" character, that isn't in a string, is ignored.
Among other things, this allows us to put a "#! /path/to/viewer" at the start of the file. Neat.
This is really more of an viewer thing, but if the script tries to call an action that doesn't exist, or reference a non existent sprite, it should fail silently. It should just not change anything. Perhaps it can put it in a debugging log or something, but the viewer should never interrupt the audience if the file is stupid. They don't care if "Ronald doesn't support action 'Wave'", just don't make him wave and move on.
The viewer can only complain about things that render the movie unplayable, like an undefined coordinate system.
The filenames used throughout this document are, by default, relative to the directory that the file being played is in.
Full URI's are also accepted, which allows files to be updated.
For instance, a series of cartoons might have a title scene that is the same in every animation. It is possible that the author could host that on the internet and then any time he changes that, it changes in all cartoons, both future and previous. I'm not saying this is a good idea, I'm just saying it's an idea.
It'd be up to the viewer to do all that, or cache it or whatever.