Data List Structures in SCL

Alternatively, read about data pairs here.

It is not uncommon to want to provide a list of data that your animations can use. This can be done with "create data as list". For now, only 'list' is supported but it provides a rudimentary column/row mechanism. 'data' also provides several methods with which to access your data. First, an example data statement:

Example:

create data from list as MyList
    where completion=Done
    set
      1 2 3
      4 5 6
end

Data lists are accessed through by referencing the list, plus an access method. For example:

x=data.MyList.next and y=data.MyList.next

The above code will retrieves the next 2 consecutive numbers in the list. The access methods are:

current retrieves the current value
first retrieves the first value in the list
last retrieves the last value in the list
next retrieves the next value in the list
prev retrieves the previous value in the list
select retrieves a random value from the list
pluck retrieves a random value from the list, and will not retrieve that value again.
tofirst moves the list pointer back to the first item so you can go through the list again from the start.
Example: update data MyList tofirst

Each access method can be followed by a period then a number. That number is called the 'skip'. Therefore, if I want every third number, I skip 3:

image=data.ImageList.next.3

You can also use a skip for for pluck, prev, and select.
There is also a "completion" event that fires when the list is completed. However this is a little wonky at the moment:

the completion event is run before the last list item is emitted
the completion event can fire twice when mixing calls to pluck and next

Example

create data from list as grid
  where completion=Done
  set
    a b
    c d
end

create routine as Start
  trace into "mytrace" where value=data.grid.pluck.2
  trace into "mytrace" where value=data.grid.next
  trace into "mytrace" where value="-------------------------------"
  trace into "mytrace" where value=data.grid.pluck.2
  trace into "mytrace" where value=data.grid.next
  trace into "mytrace" where value="-------------------------------"
end

create routine as Done
  trace into "mytrace" where value="DONE"
end

In the above example, either row will be chosen at random. The first item of a row is selected with 'pluck', then the rest of the row can be retrieved with 'next'. Note however that the completion event will fire twice: once when the last pluck is retrieved, and since when the last next is retrieved.

Iteratoring Items to a Routine

You may want to iterate over an entire list passing each item to a routine. This can be done by referencing the list in the repeat parameter:

run routine ships where repeat=data.BCList.3

The trailing number indicates the list should advance by 3 data values each time the routine is run. If you do not include a skip number, then you must advance the list processing using one of the ways listed above.

Random Access

You can access any value in data to view or change it. To view any value in a list simple call the routine getdata(listname,position).

// set TitleName to the 3 value of the list
update var TitleName where value=getdata(myList,3)

To set a value in a list use "update".

// change the 4th value to "dog"
update data myList set 4="dog"

Changing Lists

push: will add a value at the end of the list.
pop: will remove the value at the end of the list and return it.
fush: will add a value to the beginning of the list.
fop: will remove the value from the beginning of the list and return it.
remove: remove the given value from the list

Example: update data MyList remove black
reset: will reset the list to its original state (as given by its 'create' statement).
renew: will re-randomize the list.
set: update a specific value in the list.
Example: update data MyList set 1="one" // sets the first value to "one"

create routine as Example
    update data LISTNAME push "shirt"
    update var NAME set data.LISTNAME.pop
    update data LISTNAME fush "dog"
    update var NAME set data.LISTNAME.fop
end

Getting List Information

Data also supports some information requests:

contains: checks if list contains a value. Returns true or false.
Example: data.MyList.contains(red)
current: returns the current item in the list without changing where you are in the list.
position: returns a number from 1 to {n} indicating at what position you are in the list as you move through it.
remaining: returns the number of items left as you move through it
count: returns the number of items in the list
first: returns the value of the first item in the list
last: returns the value of the last item in the list
fopped: returns the value that was most recently returned by a call to fop
popped: returns the value that was most recently returned by a call to pop
get: get the value at the given position in the list (1-based indexing)
Example: data.MyList.get.7

Passing Data to Routines

Sometime you don't know which data to use until the game is playing. In this case you can pass a reference to your chosen data to a routine. See the example below (which you can use in the scratchpad):

create data from list as myList1
set
  a b c
end
create data from list as myList2
set
  x y z
end
var someVar=1
create routine as Start
  if (someVar==1)
    UseList(data.myList1)
  else
    UseList(data.myList2)
  endif
end
create routine as UseList
  var whiList=arg.1 // necessary to use data
  log(whiList.next)
end

Important Points:

the data argument must be passed with the 'data.' prefix.
the routine receiving the data parameter must save the value to a local 'var'
the local var is used without the 'data.' prefix
you can assign data lists to a level using "into".