Commands and Timelines

[iarwain]

Hi,

For all those who followed the initial discussion on the forum (http://orx-project.org/forum?func=view&catid=17&id=3955&limit=20), this thread won't probably be very interesting.

Howver for those that have questions on timelines and commands, I realized that I actually never really wrote anything in the wiki by lack of time, so I though here could be a nice place for a quick summary.

Some uses for timelines/commands have already been discussed on the forum, such as: http://orx-project.org/forum?func=view&id=5419&catid=16#5419 but I don't think it's still very visible.

There's also a tutorial (code/data only, no wiki entry yet) that could be interesting in that matter: https://bitbucket.org/iarwain/resource

That tutorial is actually focusing on the Resource module (not the topic here) but it contains a fair amount of commands/timelines.

So here we are...

-= Commands =-

==============

Commands are small pieces of code stored in a literal way (ie. as strings). They're quite slower than calling actual code directly, however their huge advantage is that they can be executed from within the config (via timeline tracks) or via the in-game interactive console (default toggle key: ` [backquote]).

In the console, one can list all the available commands by executing the command: Command.ListCommands

Commands have all their parameters literally described (type + name) and one can use the Command.Help command to get this info. Ex:

Command.Help Command.ListCommands

By typing this in the console, we'll see that Command.ListCommands takes 0 mandatory parameters but accepts an optional one. That optional parameter is a prefix to narrow the list of commands.

If we want to list only the commands from the Object module, all we have to type is:

Command.ListCommands Object

The command execution environment comes with a shared stack allowing for simple communication between two command calls.

In order to do so, special "keywords" are used in order to push (>) a result on the stack and pop (<) a parameter from it.

*Always make sure to balance the pushes and pops!*

Ex:

> Object.Create MyObject ; This command creates an object from the config section [MyObject] and pushes its ID on the stack

Object.Delete <          ; This command pops the object ID from the stack and feeds it to Object.Delete, which deletes the object (who would have guessed ^^)

There are quite a lot of commands already defined in orx (and always growing), users can also easily add their own: see the orxCommand_Register() function.

Some of the most useful commands can access the config at runtime, with both read and write accesses. This actually allows for a much more advance communication system between commands, even if they're called at different times.

Ex:

> Object.Create MyObject           ; Creating MyObject, pushing its ID on the stack

Config.SetValue RunTime MyObject < ; This will pop the ID from the stack and store it in the config section [RunTime] with the key MyObject, allowing any further commands to retrieve it

Used this way the config system becomes a very useful live storage (which can also be serialized, making it pretty good for savegames too). =)

Let's now say one wants to display the FPS counter. As its rendering is controlled via the config property Render.ShowFPS, by typing the following command in the console, the user will make the FPS counter appear:

Config.SetValue Render ShowFPS true

Please note that commands are *not* case-sensitive but config sections and keys *are* case-sensitive, so this would still work:

config.SETVALUE Render ShowFPS true

Now that we've seen commands, let's make the life of the laziest of us easier (and that includes myself ^^).

-= Aliases =-

=============

Aliases are simply shortcuts to commands (or to other aliases). They can be stored in config, in the [Console] section, and even added/modified/removed at runtime.

One can lists all the default aliases coming with orx by typing this command in the console:

Commands.ListAliases

For example, two default aliases coming with orx are Get and Set, they respectively map to Config.Get and Config.Set.

Knowing this, Config.GetValue Render ShowFPS can be rewritten: get Render ShowFPS

There are a bunch of other aliases defined by default and users are encouraged to add their own in order to make their life easier. :)

-= Timelines =-

===============

Timelines are simply a collection of tracks. Each track being a group of commands ordered in time.

Timelines are usually associated to an object and will get evaluated as long as the object is alive and active. An object reference timeline tracks using the config property TrackList.

Tracks can also optionally loop.

They also understand an extra keyword that reference the object owning the current track instance: ^

For example, let's say we want to have a track that will make an object half-transparent after 2 seconds, here's how to do it:

[MyObject]

TrackList = HalfOpacityTrack

[HalfOpacityTrack]

2 = Object.SetAlpha ^ 0.5 ; At the time T = 2s, we execute the command Object.SetAlpha ^ 0.5, where ^ will be replaced by the ID of the owner

Please note that more than one command can be executed at a given time T by defining them in a list (delimited by the # character).

Let's say we want a slightly more advanced behavior: an object that acts like our mouse cursor, here is how we can do it:

[MyObject]

TrackList = CursorTrack

[CursorTrack]                                             ; This track is responsible for moving the owner object "under" the mouse position.
0               = > Mouse.GetPosition                   # ; Gets mouse's cursor position (screen space) and pushes it on the stack.
                  > Render.GetWorldPosition <           # ; Pops it from the stack, gets its value in world space and then pushes it on the stack.
                  > + < (0,0,0.01)                      # ; Pops it, adds a slight offset on Z to make sure it'll be in camera's frustum and pushes it.
                    Object.SetPosition ^ <                ; Pops the final position and updates the owner object with it.
Loop            = true                                    ; Let's do that again next frame!

I think those should cover most of the basic grounds of commands and timelines, let me know if you have any questions! :)

Cheers,

Rom

[Matt Gallais]

Excellent, c'était très clair! :)

--
You received this message because you are subscribed to the Google Groups "orx-dev" group.
To post to this group, send email to orx...@googlegroups.com.
Visit this group at http://groups.google.com/group/orx-dev?hl=en.
 
 

[Konrad Klimaszewski]

Wow, great tutorial.

Finally I think I got the gist of timelines :-D, thanks.

Cheers,
Graag

[iarwain]

Glad you both appreciated it. Next in line: the resource module. :)

Rom