Binksi syntax and shortcuts

bipsi + ink = ♥

Binksi comes preloaded with additional syntax and shortcuts to help you take advantage of all bipsi functionalities on the ink side and, expose all ink functionnalities on the bipsi side.

Below you will find :

  • Additional Bipsi functions and variables to be used on the bipsi side
  • Additional Bipsi event properties to expose bipsi events to ink
  • Custom ink syntax to refer to bipsi event and call bipsi functions inside your ink

Additional Bipsi functions and variables

Theses variables and functions are available in all javascript fields of events.

  • STORY : the Story object as provided by inkjs.
  • SET_INK_VAR(varname, value) : save the variable varname inside of ink with value value.
  • GET_INK_VAR(varname) : extract the value of the variable varname from inside of ink.
  • DIVERT_TO(knot_name) : jump to the knot knot_name and continue the story from there. (this is equivalent to ChoosePathString)

Additional Bipsi event properties

  • say-style, JSON : say-style will behave for all text said by ink as if it were said by regular dialog. If a say-style is defined on the player character, all said text will default to that style.

Custom ink syntax

These custom snippets are to be written in your ink story.
They extend ink syntax and will be interpreted by the binksi engine at runtime.

Tagged choices

  • * [tag: mytagname] or +[tag: mytagname] :
    Tag a choice inside of your story if you want it to be actionned by an event in your bipsi scene.
    Add an event inside of you bipsi scene and add a tag with the same name.
    If your avatar touches an event that has the same tagname as a choice, this choice is triggered in ink and the story continues.
    Note: tagged choices do not prevent your avatar from moving in the scene.
  • * [auto: invisible action] or +[auto: invisible action] :
    When the bipsi players encouters an auto choice, it will automatically use it.
    It is very useful if you want to hide some choices during play while keeping them around in your ink file.
    When encountered, the story continues.
  • Classic choices :
    When the bipsi players encounters a non-tagged choice, it will stop everything happening in the bipsi scene.
    The avatar won’t be able to move until an option has been chosen.
    A maximum of 4 choices will be displayed, each a recommended maximum of 38 characters (this is not enforced but adding longer text can lead to unforseen consequences).
    The player will be able to chose an option using arrow or swipes in the 4 directions.

Ink tags

  • #TITLE :
    If a text is tagged with #TITLE, it will be displayed in bipsi’s TITLE format (text only in the middle of the bipsi game area).

  • #character or #character-sentiment : Portrait mode :
    If a text is tagged with #character-sentiment, it will try to find an event tagged character and look for a file field named sentiment (sentiment will default to "neutral" if given sentiment file is not found.). It will display the dialog using “portrait mode” :

    Neutral Happy
    portrait mode portrait mode

    Example 1: Hi there, fellow binksi user. #rosalia-neutral

    Example 2: I hope you enjoy using this tool! #rosalia-happy

Custom syntax in ink

Just write those in your ink script as if it were text.
They should be written alone on a single line.

  • SPAWN_AT(teleport_name) :
    When encountered in the text of the story, bipsi will try to teleport the avatar on an event tagged with teleport_name.
    The name should not be enclosed in any quotes.
    If the teleport target does not exist, nothing happens and the story continues.
    Tip: teleport_name can be a printed variable, (eg: SPAWN_AT({lastVisitedRoom})). Example: See the example file in the repository.

  • SPAWN_AT(teleport_name, event_name) :
    When encountered in the text of the story, bipsi will try to move the selected event event_name on an event tagged with teleport_name.
    Both names should not be enclosed in any quotes.
    If the teleport target or the event do not exist, nothing happens and the story continues. Tip: You cannot create new event on-the-fly, you should create a “store room” where you can take event from and put them back.

  • CUTSCENE(event_name[ ,field_name]) :
    When encountered in the text of the story, bipsi will try to trigger the cutscene found in the javascript field field_name on a event tagged with event_name. field_name is optional and will default to the javascript "touch" field.
    Both names should not be enclosed in any quotes.
    The field identified by field_name must be a javascript field. In the context of the javascript field, all usual variables can be used. The EVENT variable references the event named in the first argument.
    If the event target or the field do not exist, nothing happens and the story continues. Example: See the example file in the repository.

Rules of touch

  • if multiple events are on the same square, they are all touched (this behaviour differs from bipsi)
  • if a touch script field is defined, only it will be triggered
  • if the touch matches a tagged choice (see above) then the before script will be triggered before sending the choice to ink ; standard events and then after script will be triggered right after the first paragraph sent by ink.
  • otherwise standard bipsi touch rules apply.