Skip to content
This repository has been archived by the owner on Jan 3, 2023. It is now read-only.

Notes for Script Creators

Jump to bottom
Sean McKinnon edited this page Dec 20, 2018 · 7 revisions

Notes for Script Creators

This page is out of date and needs updating

This page contains information relevant to creators of item filter scripts who want users of their script to be able to fully leverage the power of Filtration.

Parsing Rules

  • Filtration parses scripts from top to bottom, splitting the script into blocks each time it encounters the keyword Show, Hide or # Section:
  • Any line starting with # before the first block is considered to be part of the script description (except the line directly above the first block if it is a comment, as that line is the description for the first block (see below)).
  • The line directly preceding a Show or Hide block is considered to be the description of that block if it starts with #.
  • Any comments on the same line as a filter item are ignored and stripped out (except for Show/Hide lines and Colour Block Items).

Sections

Sections are a Filtration specific feature that represent breaks or bookmarks within a script. They are represented by a line starting with # Section: and cannot be longer than a single line. Any other comments in between Show and Hide blocks are ignored, which will result in loss of comments for existing scripts with section comments not created by Filtration.

Disabled Blocks

Disabled blocks are blocks that are saved in a filter file but won't be used in game (due to being commented out). Filtration implements Disabled Blocks by wrapping them in two special lines - #Disabled Block Start and #Disabled Block End. For example:

#Disabled Block Start
# This is a disabled block
#Show
#    ItemLevel > 10
#    DropLevel < 15
#    SetBackgroundColor 255 0 255
#Disabled Block End

These blocks can then be enabled/disabled from within Filtration by clicking the relevant buttons on the ribbon menu.

Themes

Filtration supports Themes via the use of "Theme Component Tags" on colour Block Items. For more details of Themes and how to enable them in your scripts check out the Themes wiki page.

Block Groups

Block Groups are a powerful tool to allow users of your script to quickly toggle the Show/Hide status of multiple blocks at the same time, in a hierarchical fashion. Block Groups are denoted by a comment after the Show/Hide line, and can be nested by using - as a separator.

Example:

Show #Gear - Progression - Weapon - One Hand Maces
    BaseType "Behemoth Mace"
    Rarity <= Magic
    Sockets >= 3
    SetFontSize 28

Show #Gear - Progression - Weapon - Two Hand Maces
    BaseType "Coronal Maul"
    Rarity <= Magic
    Sockets >= 4
    SetFontSize 28

The above blocks will result in 5 unique BlockGroups being created - Gear, Progression, Weapon, One Hand Maces and Two Hand Maces. Note that the Weapon BlockGroup is considered to be one and the same for both blocks, because it falls in the same place hierarchically. The above blocks are displayed in Filtration's Block Group Browser like so:

Important Note: In order for BlockGroups to appear properly in Filtration the script file must include # EnableBlockGroups line somewhere in the script header like so:

# Script edited with Filtration - https://github.com/ben-wallis/Filtration
# EnableBlockGroups
# Sai's Custom Strict Filter for Mapping. Made with Filtration v1.1.0
Advanced Block Groups

Filtration also supports "Advanced" Block Groups - these are Block Groups that should generally not have their Show/Hide status modified by users, but are provided for Advanced users who may wish to make use of them. If you include Advanced Block Groups in your script, you should explain their purpose in your Script Description.

Advanced Block Groups are denoted by the ~ character. If a Block Group is marked as Advanced, then all its Child block groups are also considered to be Advanced. For example:

Show # ~Advanced Group - Sub Group - Another Group

and

Show # ~Advanced Group - ~Sub Group - ~Another Group

The above examples will result in identical results - three Advanced Block Groups. You cannot have an Advanced Block Group that has non-advanced child Block Groups.

Advanced Block Groups are denoted in Filtration by a red highlight, in both the Block Group Browser and the main block editor. In a future release it is planned for Advanced Block Groups to be hidden from users by default unless they click a Show Advanced Block Groups toggle button.

Example of Advanced Block Groups in Filtration:

Clone this wiki locally