artofsequence / aosl Goto Github PK

This document needs to be finished ASAP: https://github.com/artofsequence/aosl/wiki/Understanding-AOSL-1.0

Also, move it into the repository, don't keep it in the wiki.

Currently the Canvas is a static vectorial space in which the sequence plays by changing progressively it's content.
The current way of moving the canvas point of view without moving the objects positions is to change all objects position together to give the illusion of moving a camera.

We need a way to simplify it: add a change which transform the canvas "camera".
This might also imply to allow setting an initial camera transformation.

Replace the current property tag implementation to allow just having JSON data as value.

Use this regex to validate the property content: http://stackoverflow.com/questions/2583472/regex-to-validate-json

Currently objects and the storygraph can hold properties, which are user-defined associated data.
However there is no defined way to modify these properties. Scripts can theoretically modify them but it's a last-resort feature.

Add a change type which modify the properties of an object or of the storygraph.

First specification document of XAOSL.
Should the version be independent of the AOSL version?

See discussion: https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

Currently it not always possible to have one AOSL file specify the same story whatever the capabilities of the player interpreting it.

Basically, we need a way to specify different objects and resources to be used instead of a default one in case some specific context is met.

For example, if we have an image with red and green only, and we want to support color-blind people, we may need to use an alternative image if the player have a specific capability information saying it's color-blind.

This might be related to localization issues too. See #3

One way to do this would be by adding a "capability" attribute to both objects and resources. This attribute would be optional and when used would contain a sequence of identifiers of capabilities (which might or might not be specified).
Then an object or a resource could be defined with the same id, but different values in the capability attribute. When looking for the object or resource using it's id, either there is only one, to it use it; or there is more than one, then it look at the capability attribute: it uses the one with the highest count of capability ids that match it's current state, and if non match, it use the one which have none, which is the default. It's basic pattern matching in the same way than function overloading in programming languages.

For example:

<sprite id="mysprite" > ... // used by default
<sprite id="mysprite" capability="black&white" > // this version should be preferred if the player can only display black&white - preffered if the user isn't colorblind
<sprite id="mysprite" capability="black&white colorblind"  > // but this version should be preferred if the player is used by a colorblind user OR (if the display is black&white AND the user is colorblind)

Not sure it's the best solution yet, but I think it would limit verbosity in the AOSL file.

Related to #8.

The idea is to allow the user to define rules for the "#next" navigation transition to run some algorithm to determine what transition will be chosen.
There are several ways to do this:

• use scripts as algorithms;
• provide a set of useful algorithms, which parameters can be tweaked;
• ...

AOSL needs to have some ways to handle text objects and this is related to localization issues and capabilities issues too. This is a very complex feature that need discussion and great care I think.

Discussions:

• https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0
• https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/60HykUYyCGo

My current thinking is:

• add a text resource, which can hold text in-place or can be a source file;
• we assume that the text resource contain pairs of id/text, so one text file can contain text for several different text objects;
• we also assume that the id/text pair exist for different languages, to manage text localization (maybe find some kind of standard format for this)
• add a "textarea" object which have graphic properties and, additionally, a "shape". It then refer to a text resource and a text id (or maybe only a text id? or an address composed of the resource name and the text id?) The shape gives the graphic area in which the text can be displayed (like in Adobe In-Design).

Then, there is the text formatting problem to solve. For this, one option would be to use CSS. However this might complexify things a lot too, as CSS is not made only for formatting text, but whole graphic documents.

(This is a very advanced feature.)

Provide a way to specify algorithms as resources.

The idea would be to allow generating content "on the fly" using context information and pre-defined generation rules.

Add the possibility to identify the sequence using an official standard identifier like ISBN.

Might be added either to the Meta tag or to the Sequence tag as attribute.

To allow modifying flow of one thread ( #9 ), one solution would be to rely on property data which can be changed ( #25 ). However there is a missing part: we need to allow a transition only if it match conditions like having a property set to a specific value.

To allow this, we need a condition element in transitions which define that condition. The condition could be an assertion on properties values or on object states.

Markdown formatting is simple but too limited for some kind of documents like the Understand AOSL document. Switch to asciidoc for these.

All effects are function of either time or an input value (or maybe some other source). If an effect is set to rely on time, it would just be executed through time and end. If an effect is set to rely on input, then the effect behaviour will depend on the value of the input, which varies between 0 and 1. The input value changes are implementation-dependant.

This allow us to have animations between nodes which for example can show a paper page turning, following the movement of the finger.

In case of input flow, a property of the input have to be defined as the information to observe to update the effect state. For our page turning example, that would be the input cursor (or finger) x axis on the screen (0 is left, 1 is right, in left to right reading experience).

Scripts should allow the user to add some dynamic behaviour, by manipulating the objects outside of the story structure.
There is no specification of an API to access and manipulate infos from the system.

See: https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

"Standard" document specifying the AOSL format v2.0.

Streams (video, audio) currently are played independently from each others, no interaction is possible.

However when we want to be able to control if stream should be playing when another stream didn't finish yet. Also, we want to be able to differentiate streams that should play simultaneously and streams that shouldn't.

Therefore, we need a way to associate a channel name (or number) to a stream which indicate a queue in which the stream will be queued instead of playing immediately. If no channel is set, then the stream should be played immediately.

To clarify: if the same stream, say a sound, should sometime be queued, but sometime be immediately be played, then two different audio objects (using the same resource) can be used instead of one.

This might or might not be an issue but some of the tag names seem to be a bit ambiguous to some people. As AOSL isn't widely used yet, it is still possible to change some names before tool implementers start to rely on the current names:

Potential names to change:

• stage (as in a stage in a process, not the place where a pay is happening);
• move (it's a "set of change" so "changeset" might be better, or maybe "transition" but it might be misleading);

Current idea:

• stage => node
• story => storygraph
• move => transition (potentially: passage, way, walk... )
• resource => media ?
• ...

From https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

Here is another feature I felt the need while experimenting with the coming AOS Web Player demo:

.7. Multiple Lecture Threads

The general idea is to allow several, maybe unrelated, parts of the story graph to be read in parallel.
For example:

-> X -> Y ->Z    (this one is looping from Z to X)
      ^____/

-> A -> B -> C -> D -> E -> F -> G -> H -> I -> J

Here the story starts with two beginning stages: A and X. Each "next" move will move both threads in parallel, resuling in this sequence of stages:
A , X => B , Y => C , Z => D , X => E, Y => F, Z => G, X => etc.

The typical usage of such feature would be to have a background loop sequence and front non-loop action.
For example, imagine X Y and Y being stages showing the same background but with some changes like rain drops.
Allowing this feature would help telling a story with recurring parts of sequences in parallel.
The need came when trying to write such a sequence: with AOSL 1.1 we have to copy the X->Y->Z moves "by hand" in the main A->...->J sequence.
This is very problematic, in particular when you want to make modifications to the number of stages in the main sequence.

This feature would be cut in several parts:
a. allow the "begin" attribute of a to start with several stages.
b. allow a move to target several stages (the "to" attribute is currently limited to only one target).
c. add a way to express a "end of story" stage for the player to end any other thread when this expression is met.

The need for c is apparent in the example I gave: here we have the X->Y->Z part that is looping with no end condition,
so a player would not end the sequence when J is met but would continue to allow a "next" move with no limit.
This can be good for some interesting storytelling experiments, but in the same time most use would end at J.
To fix this the immediate thinking would be to have some scripted condition in J and X/Y/Z to make these last stages move to another "end" stage that would have no other move.
But that is a bit boilerplate to express a simple thing: "stop reading here".

Provide a FindAOSL cmake module to help with projects using CMake and that need to locate the AOSL files.

"Human readable" introduction to XAOSL 1.0.

Basically, we need a way to allow jumping to a specific part of a story, and listing the different points where we can jump to.

From https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

1. mark stages that can be jumped to (chapters?) to allow players to provide a way to jump there

When a sequence have branches and/or loops, it is very hard to provide a way for the reader to jump directly at a specific stage in the sequence.
On the algorithmic side it is not hard (using default moves and/or Djikstra graph search).
The problem is more to find a way to represent the full sequence for the reader to point where to go. A graph is not intuitive and show too much to the reader.
A timeline would be possible but maybe not a good idea if the story have several branches that don't merge later.

The solution I think would work best would be to allow the author to mark specific stages as being points where the reader can directly jump.
It would be like chapters in a DVD/BlueRay, but it would allow to mark stages in branches too.

We need an official specification which would be more technical and complete than the other documentations (https://github.com/artofsequence/aosl/wiki/Understanding-AOSL-1.0).

The specification should follow formal language.
It might not be coupled to XML, or it might use XML as an example only. The important thing with AOSL is how the data should be organised and interpreted. So it is discutable that the specification would be XML-specific. However it would help simplify writing the specification.

The specification should be in a file into the repository, not in the wiki.

Basically, a way to jump to another sequence from a navigation action.

From https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

.5. jump to another sequence

It would be useful for the author to be able to say to play another sequence from inside one sequence.
One of the reasons to use this would be to write "series" of sequences, but allow the reader to jump from an episode to another without any cut.
The other reason is to allow a very big sequence to be loaded in separate chuncks of resources.
A player can load resources the way it prefer, but if some resources are very heavy, it can be useful to make sure all pllayers unload these resources once not needed anymore.
To be sure it is done, having these heavy resources part of sequences and then jumping to another sequence when not needed is useful.

This need thinking too. Depending on the player implementation and context, widely different possibilities could be offered.

From https://groups.google.com/forum/?fromgroups=#!topic/aos-dev/GGKnRA95Ah0

.6. Random Navigation

Allow the author to let the player choose the next move in a random way (instead of in a deterministic way).
That would allow authors to have minor variations in the experiences of the user for cheap.

This seem to be cheap to implement.

The license (MIT) information is missing.

Some guidelines to apply the license:

Applying The Licence
Once you have chosen the licence you wish to use and confirmed that you are legally entitled to license all the code in your project, you must apply the licence so that people can see it. It is not sufficient to simply state that your code is available under a specified licence; you also need to ensure that it is prominently displayed in all appropriate locations.
At a minimum you must:

• state on your website which licence is applied (preferably on your home page and your downloads page)
• provide the full text of the licence on your website
• provide the full text of the licence in the root directory of your source project (usually in a file called LICENSE.TXT)
• provide a boilerplate notice in the head of each file in the source distribution (The boilerplate text used varies from licence to licence. You will usually find further discussion on how to apply a licence documented alongside the licence in its original home.)
• provide the full text of the licence in the root directory of your non-source project distributions (usually in a file called LICENSE.TXT).

There are tools available that can help with the application of a licence to your source files. For assistance with this and other code audit exercises, please contact OSS Watch.

From: http://www.oss-watch.ac.uk/resources/opensourceyourcode

"Human-readable" introduction to AOSL 2.0.

Effects should currently be applied at the same time when going in a transition.

Add a priority attribute to allow Effects to be executed by order of priority.
For example, if we have in the same Transition:

• effect A have priority 0;
• effect B have priority 1;
• effect C have priority 1;
• effect D have priority 2;

On executing that transition, A will be executed first, then B and C simultaneously, then D, then the transition will be done.
By default, all effects should have priority set to 0.

ignore me

The "meta" tag contain too much unused fields. A big cleanup is necessary.

Also, most meta info should be available outside the AOSL file, in particular in the archived format.

Specify a set of effects that should be available on in all players.

First choose the list of effects, then add them to the specification with how to set their data.
For a first version, a combination of common tweening effects from JQuery, Cocos2D and other widely used libraries should work fine and be easy to implement in players.

All effects are function of either time or an input value. If an effect is set to rely on time, it would just be executed through time and end. If an effect is set to rely on input, then the effect behaviour will depend on the value of the input, which varies between 0 and 1. The input value changes are implementation-dependant.

Currently, AOSL is just XML data specification. The resources it manipulate are accessed via uris so it depends on the context of use to be able to find resources.
Also, an AOSL file contain too much Meta data which could have been put elsewhere.
The resources are totally dissociated form the file containing the AOSL data.

To help providing a universal format for a file which contain all the resources and the AOSL data, we need another format based on AOSL.

That new format would be partially inspired by the EPub format:

• http://en.wikipedia.org/wiki/EPUB
• http://idpf.org/epub/30/spec/epub30-overview.html

Basically, the specification for such format would need to describe:

• an archive format to use which would contain both AOSL data and resources used by these data - AOSL data would refer only to resources inside that archive;
• the way the content of the archive would be organized (put all resources in a directory for example);
• additional (but optional) files like meta-data (author, modification dates, etc);
• potentially, non-specified data, to allow using this format as an edition format too;
• a list of allowed resource types: we need to limit the kind of resources to a specific list to help implementer of interpreters to only support that list and not more or less. One way would be to use HTML5 specification as a base to create that list.

For now, I'm calling this format *XAOSL (pronounced xao-ess-el), for "cross AOSL" *.