List Var API Issues and Questions

GameUX 4 months ago in Game Creator updated 4 months ago 6

1) ListPush using index generates a compile error

Works: VariablesManager.ListPush(objSpawnId, ListVariables.Position.First, 789);
Breaks: VariablesManager.ListPush(objSpawnId, ListVariables.Position.Index, 0, 789);

Assets/CustomScripts/Managers/PlayerManager.cs(45,22): error CS1501: No overload for method 'ListPush' takes 4 arguments

2) From the API page, "Setting" and "Inserting" are unclear. In the example above, would the result be a "set" to change the value of index 0 or an "insert" before (or maybe after) of a new item?

3) Whichever ListPush does, how do I get the alternative action, so I'm able to set item 0 to a new value, insert a new item before item 0 and append an item after the end of the list?

4) Position.Next appears to loop from the end to the beginning. If this is working as designed, it should be documented.

5) There is no obvious way to get the count of items in list. Without this, it is unclear how to iterate through the entire list.

Unity version:
Game Creator version:

The second method breaks because you have an extra parameter in the method call. It should be:

 VariablesManager.ListPush(objSpawnId, ListVariables.Position.Index, 0);

Being 0 the index 0 of the list.

Setting a value simply updates the value at a certain position, while insert moves all the values from that position one cell forward to make room for the new value.

So if you want to insert the value 3 in the list [1,2,4,5], you need to set the insert index to the 3nd position:

Insert index 0 => [3,1,2,4,5]

Insert Index 1 => [1,3,2,4,5]

Insert Index 2 => [1,2,3,4,5]


Next, Current and Previous all refer to the Iterator. That is documented. The iterator (although there's a bug that we're currently fixing) points to the index of the last element read. So, following the previous example, if you try to access the 3rd element, the Current selector will point the 3rd element, while Next will point to the 4th and Previous will point to the 2nd.

Hope this resolves the questions. I agree that the List Variables isn't very non-programmer friendly and still needs further documentation, but it's a quite recent feature and I'm still fiddling and getting a sense of how should it behave.

1) Where is the object value parameter?

VariablesManager.ListPush(objSpawnId, ListVariables.Position.Index, 0);

2) The docs https://docs.gamecreator.io/game-creator/systems/game-creator-api/variables-access show ListPush and ListRemove, but there is no example for setting (ListSet?)

3) A link from the API back to https://docs.gamecreator.io/game-creator/game-creator/variables/list-variables would be very helpful. I had read that page twice, but forgot about when I was reading about the API. 

Complex data structures are just not friendly to programmers and non-programmers alike. What you are doing with List Variables is brilliant. Keeping the design and terms close to the C# structures you have based them on should be a good way to cover all the use cases and keep your code as simple as possible. 

1) Sorry about the confusion, I'll update the documentation so it's clearer. When you want to add an object to the list at a specific index, you use:

VariablesManager.ListPush(gameObject, [INDEX], [VALUE]);

However, if you want to add an object using an automatic indexer (the Next iterator, Previous, Current, Random, ...) you use:

VariablesManager.ListPush(gameObject, [ListVariables.Position], [VALUE])

When you see this message the documentation should be already up to date.

2) I am hesitant to add a "Set Variable". I can add it, but I intentionally left it, since List Variables are supposed to only add and remove elements from a list, not update them. At least I haven't thought of any use-case where this could not be replaced with a Local Variable. But this is something I am open for discussion and might be persuaded to change.

3) Updating this too right away :-)

Thank you!

Thank you for the clarification that list vars are not updatable. One should be able to do a ListRemove and then a ListPush using the same index to get the same result as a ListSet would. My use case is that I want to use GC's save/load system to save a list of floats that grows with the game.

For now I've integrated JSON.net from the Asset Store and use a global string variable to save and load the data. Simple but not performant for lots of data. Hoping for a better solution to be added to the Darkside API to persist complex data structures with GC's save/load system.

Thanks for bringing this. So the main issue here is performance. There's another thread were it was discussed the decision of using a single string value to store all data.

Some users made very strong and good points on why this wasn't the best choice. I've created a ticket to change this for the next major iteration. If an object hasn't changed since the last game save, it shouldn't be overwritten with the same value (as it does now).


A string of JSON data is very flexible. How much "Darkside" features you offer is a key question to what your product vision is.

A simple approach could be to have a list vars of strings that will only auto-save when I update one of them. That way I could easily put all by objects on one and have slow performance, or I can break my objects into thousands of list vars instances and quickly save a little that just changed. As a dev, I could do all the loading and saving myself, but have a handy set of list vars that saves everything else is very helpful. I love how it easy it is save a new global I just thought of along with all my other data.