Advanced Puzzles Reference — Soft8Soft
Description: How to use puzzles to implement advanced features in your apps, such as networking, interation with JavaScript code, data conversion, state saving/restoring and more.

# Advanced Puzzles

Use these puzzles to implement advanced features in your apps, such as networking, interation with JavaScript code, data conversion, state saving/restoring and more.

## Contents

- Puzzles Reference
  - comment
  - exec script
  - call external function
  - load data
  - send data
  - loaded data
  - stringify json
  - parse json
  - read CSV
  - connector
  - connector (slot-based)
  - save state
  - undo state
  - all variable names
  - variable value by name
  - JavaScript object
  - wait promise
  - promise value
  - get procedure
  - call procedure
  - add event listener
  - remove event listener
  - dispatch event

#

## Puzzles Reference

#

### comment

This puzzle does nothing except places a comment line to make your script easier to grasp. It also adds a JavaScript comment line to visual_logic.js.

#

### exec script

This puzzle executes the specified JavaScript code. The puzzle uses Ace Editor for displaying and editing the content. See the relevant keyboard shortcuts here: Default Keyboard Shortcuts. The puzzle can be resized to change the editor's width and height.

You can use the following built-in variables:

- app — the application instance, see App for more details
- v3d — the v3d namespace which contains all the engine modules
- puzzles — the "Puzzles Logic" object containing procedures defined in puzzles, API for physics puzzles, etc...
- VARS — variable puzzles can be accessed through this object
- PROC — procedure puzzles can be accessed through this object

#### Specifics of using built-ins regarding to "Init" and other tabs

- The app built-in variable is not available for this puzzle if it's used inside the Init tab, since at that stage the application is not properly initialized yet.
- Variables and procedures declared in the Init tab can not be accessed from other tabs via VARS and PROC and vice versa.

#

### call external function

Executes a function specified in the JavaScript code of the application. Optionally passes parameters to be used as function arguments.

In order to add a function to JavaScript code, open the application .js file (for example, my_awesome_app.js located in the my_awesome_app folder in the applications folder) with any text editor. Search for `prepareExternalInterface` and add your function inside that declaration (between the curly brackets), so that it looks like this:

`function prepareExternalInterface(app) { app.ExternalInterface.myJSFunction = function(numericArg, textArg) { alert('Got some params from Puzzles: ' + numericArg + ' and ' + textArg); } }`

#

### load data

Load data from a specified location. The retrieved data can be accessed via the loaded data puzzle. JSON objects are automatically converted to dictionaries, all other data types are returned as text values.

By default, the results retrieved by this puzzles are cached, so the subsequent calls return the same value. To disable caching, click on the gear icon and activate the disable caching checkbox. The enable "on error" slot setting is used to handle errors via additional on error do slot.

#

### send data

Send a specified data to a remote location using an asynchronous POST HTTP request. The retrieved data can be accessed via the loaded data puzzle. JSON objects (both sent or received) are automatically converted to dictionaries, form data values are sent as is, while all other data types are sent/received as text values.

The enable "with headers " slot is used to provide additional request headers via the dictionary object. The enable "on error" slot setting is used to handle errors via additional on error do slot.

Keep in mind, that browsers might keep local copies of retrieved assets for optimization purposes. To avoid browser caching, an additional parameter can be used to change the URL each time you make a request. To add this parameter, use the set URL param and elapsed total puzzles:

#

### loaded data

Returns data retrieved by the load data or send data puzzles.

#

### stringify json

Converts any data (dictionaries or lists in most cases) to JavaScript Object Notation string.

This puzzle is useful for saving something to an HTML element data attribute or to the local storage, sending over network, updating a remote database, using as page param, etc.

Example:

#

### parse json

Interprets text (or Data URL) as JavaScript Object Notation data which is returned in a dictionary.

The puzzle does the reverse operation to stringify json:

#

### read CSV

Interprets text (or Data URL) as comma-separated values. Returns a list of table rows, with each row represented as a list of values. The delimiter can be selected with the drop-down to correspond a CSV file's export settings. from row value denotes how many rows will be skipped starting from the top.

Table rows and values are accessed by their numeric indices starting from `0`.

#

### connector

This puzzle facilitates connecting other puzzles with each other, to make it more convenient to move, delete and use them in other puzzles. The most notable application is to join load sound or load video puzzles into a single group to organize preloading of media resources in your application.

#

### connector (slot-based)

This puzzle facilitates connecting other puzzles with each other, to make them more convenient to move, delete, comment, and use in the library.

#

### save state

Saves the state of specified objects and/or the values of variables specified by their names. The objects are cloned and stored in memory. The values of the variables are retrieved and stored in memory for each specified variable name.

If this puzzle is called several times, the states are saved in sequence so that it is possible to return to any previous state with the undo state puzzle.

#

### undo state

Restores the state of objects and/or variables saved with the save state puzzle.

If this puzzle is called several times, the states are restored from the saved sequence (if any) which makes it possible to return to any previously saved state from the stack. Sometimes you need to catch the situation when there is no saved state present in the undo history, e.g to make changes in the UI. For that, use the state counter variable:

#

### all variable names

Returns a list with the names of all variables used in Puzzles.

#

### variable value by name

Returns the value of a variable specified by its name. This puzzle works similarly to the standard variable value puzzle, yet does not require to select a variable from the predefined dropdown menu.

#

### JavaScript object

Returns a given JavaScript object.

You can get the following JavaScript objects with this puzzle:

arguments

  Returns the list of arguments of the currently executed function. Can be used to get arguments of Puzzles procedures or additional arguments passed to internal Puzzles callbacks.

  For example, when using when clicked puzzle, you can get the internal JavaScript event which triggers the puzzle logic using the first argument of the callback executed behind the do slot. In the example below we use this event to get X and Y coordinates of the mouse pointer:

  The following puzzles support advanced options:

  - when clicked, when hovered, when dragged — mouse or touch event which triggers puzzles in the do slots.
  - after, set timer — timer ID returned by the puzzles' setInterval() call.
  - every frame — delta time and total elapsed time.
  - on event of — event object.
  - on session event — WebXR event object.
html element

  Returns a dictionary which represents a DOM object for the specified HTML element. This is useful to access HTML element properies which are not yet supported by the set property or get property puzzles.

form data
  Get FormData object for the `<form>` element. You might use it for e.g. sending custom forms to email.
this
  Value represented by JavaScript's `this` keyword.
window

  Return the top-level `window` object as dictionary value.

#

### wait promise

Wait for the promise to be resolved or rejected and return its value (or rejection reason) in the promise value puzzle.

This puzzle may be required to get value of the export to gltf and generate normal map puzzles. Being async puzzles by their nature, these puzzle do not return resolved values immediately. Instead, they return promise values which are implicitly resolved in the puzzles they are used as inputs. In some rare cases, however, this resolving does not happen. In these cases you should use wait promise to resolve promise values.

#

### promise value

Resolved promise value (in case of resolved promise) or error string (in case of rejected promise).

#

### get procedure

This puzzle can be used to obtain a procedure defined in Puzzles. The returned value can be assigned to a variable or passed into another procedure as a parameter and then executed later via the call procedure puzzle.

#

### call procedure

Executes Puzzles' procedure obtained through the get procedure puzzle. Optionally passes parameters to be used as procedure arguments. There are 2 variants of the "call procedure" puzzle — with and without a return value.

#

### add event listener

Adds a listener to the specified event type, i.e. executes Puzzles' procedure obtained through the get procedure puzzle when the specified event type is raised.

#

### remove event listener

Removes listener from the specified event type, i.e. removes given procedure from the event type listener.

#

### dispatch event

Trigger an event of the specified type. Optionally passes parameters to be used as procedure arguments (i.e. the same arguments for each procedure).

## Having Troubles with Puzzles?

Seek help on the forums!