niedziela, 2 sierpnia 2015

#Stencyl: Matrix behavior


Topics:
  • Download
  • Behavior's history
  • Matrix in matrix behavior
  • Using matrix behavior
  • List of trigger events
  • Storing in matrix something different than numbers
  • Implementation details


Download
<Matrix behavior> can be downloaded together with <Zerg terrain infection> project:

Behavior's history
There are many cases when people need 2D lists or matrix for their project. Stencyl does not support in any way such problem.

My first prototype for matrix behavior was created when I need to make a map for generating maze.

Generating maze project:

The behavior worked but whole set-up was rather chaotic. As I went on with Zerg terrain infection project I decided to make matrix handling more coherent.

Zerg terrain infection project

The behavior still needs some cosmetic upgrades such as more intuitive arguments names. In current version the behavior is fully functional. I plan to develop matrix behavior in future in order to make it more user-friendly. The next version of behavior will come with presentation in form of Stencyl project.

If you need a function and it hasn't been implemented let me know.

Apparently there is another 2D list extension but I haven't used it and I doubt if there is any documentation on how to use it:

Matrix in matrix behavior

Matrix is 2D list made for storing number and numbers only. It has x and y direction. Set of entries with the same y and different x is called record. Matrix is limited in x direction and unlimited in y direction meaning you can add any number of records you like. Position in both x and y direction are indexed starting from 0.


Picture of matrix. Red numbers represent single record.

As we create matrix we name it. There can't exists two matrix with the same name - name must be unique. The newly created matrix is the added to the list of matrices. That means we can refer to matrix either using its name or using index which holds reference to the matrix. Most trigger events are available in two options _by_name or _by_index. Using _by_index is quicker but is less user friendly.

Matrix knows:
  • its name
  • its index in list of matrices
  • its number of records
  • limit in x-direction


Picture shows list of matrices with 3 matrices.

Using matrix behavior

Communication with <Matrix behavior> is based around setting attributes for <Matrix behavior> using block: <for this scene, set <> to <> for behavior <Matrix behavior> >. Then we trigger event according to what we want to do.

If what we did should return something, for example value at (x,y) position we can get it using block: <for this scene, get <> from behavior <Matrix behavior> >.

In <Matrix behavior> there is a special inactive <when created> event that allows quick copy-paste from <Matrix behavior> to other behaviors.

List of trigger events

General rule is that _by_index triggers don't check if input values makes sense. They assume you know what you are doing. _by_name triggers tend to check input values and print proper error to the console if they find something wrong.

IN - attributes you are ought to change while triggering the event
OUT - attributes you can get after you trigger the event

In <Matrix behavior> the following trigger events has been implemented:

  • add_list - create new matrix
    • Additional information:
      • You can't trigger scene events in <when created> events of scene bahavior. You need to add do after <small time> if you want to use trigger event in <when created> event of scene bahavior.
    • IN:
      • name - name of matrix; must be unique
      • size - size of record in x direction; must be bigger than 0

  • add_record_by_name - add record to the matrix with given name
    • IN:
      • name - name of matrix
      • input_list - list containing record you want to add

  • add_record_by_index - add record to the matrix with index
    • IN:
      • helper_2 - index of matrix; must be unique
      • input_list - list containing record you want to add

  • get_data_by_name - returns info(index, number of records, limit in x-direction) about matrix with given name
    • IN:
      • name - name of matrix
    • OUT:
      • size - limit in x-direction
      • number_of_records - number of records in the matrix
      • matrix_index - index of matrix in list of matrices

  • get_record_by_index - returns record from matrix with given index
    • IN:
      • input_1 - index of matrix in list of matrices
      • input_2 - index of record (index in Y direction)
    • OUT:
      • input_list - list containing a record

  • get_value_by_index - gets value at (x,y) position from matrix with given index
    • IN:
      • input_1 - index of matrix in list of matrices
      • input_2 - X position
      • input_3 - Y position
    • OUT:
      • output - value at (X,Y) in matrix with given index
         
  • set_value_by_index - sets value at (x,y) position from matrix with given index
      • Additional information:
        • It's forbidden to set value in record that doesn't exist.
      • IN:
        • input_1 - index of matrix in list of matrices
        • input_2 - index in x direction
        • input_3 - index in y direction
        • input_4 - value to be set

      • fill_by_name - matrix with given name is changed into matrix of <n> identical records. Each record is filled with the same number.
        • Additional information:
          • requires list_behavior
        • IN:
          • input_1 - number that should fill matrix
          • input_2 - number of records that should fill matrix

      • print_matrix_names - prints into console all names of matrices along with their indexes

      • print_matrix - prints into console matrix with given index
        • IN:
          • input_1 - index of matrix in list of matrices

      Storing in matrix something different than numbers

      Matrix behavior does not allow to put into matrix something else than numbers. In order to store in matrix other type than numbers we need to do it indirectly. We create additional list with objects of type we want and in matrix we keep indexes to the objects.


      Picture shows indirectly placing objects of chosen type into matrix.

      Implementation details

      In reality <Matrix behavior> keeps matrices as lists. X and Y coordinates of matrix are translated to index of list using limit in x direction. If X and Y are coordinates then index [i] in list is calculate as:

      [i] = Y * <limit in x direction> + X

      Matrix as in matrix behavior and matrix as list.

      Matrices are stored in list called <ultra_list>. Attributes of matrix under index [i] in <ultra list> are stored as elements [i] in lists:
      • name - <name_of_lists>
      • number of records - <number_of_rows>
      • limit in x-direction - <size_of_list>

      <Matrix behavior> uses one local trigger event <find_list>. <find_list> searches for matrix with <name> in list <name_of_lists> and returns index of matrix in <ultra_list> as helper_2. If matrix with given name doesn't exist helper_2 is returned as -1.


      Brak komentarzy:

      Prześlij komentarz