Instance Flags by YellowAfterlife!
Get the extension on itch.io or GM Marketplace.
This document is also available online.

Click on sections to expand/collapse them.
Quick display controls: Categories · Sections · Everything ·

General idea

Historically GameMaker instances only had a single flag ("soild"), which was mutually exclusive with filtering instances by their type/parent, but, with introduction of collision list functions, we can do better, allowing to filter by type AND an arbitrary set of flags.

So, for instance, you can check whether your character is standing on a slippery solid block, or whether that block is jump-through, or find the nearest airborne target in a tower defense game, or many other uses.

See the demo project for an example!

General structure

Setting up: Objects that you want to use with _flags function must have a variable called iflags, holding a set of bit flags or 0 if there aren't any.

You declare the bit flags yourself, usually as an enum or a set of macros:

enum Flag { A = 1, B = 2, C = 4 }

On native targets, you can have up to 64 flags.
On HTML5 you can have up to 32.

Each of the functions takes 3 arguments, flags, value, and not.

The way these work is as following (pseudocode):

var flags = .., value = .., _not = .., matches;
value &= flags; // means that you can use -1 to match `flags`
if (_not) {
    matches = (self.iflags & flags) != value;
} else {
    matches = (self.iflags & flags) == value;
}

Which means that you can do things like:

// finds an instance with both Flag.A and Flag.B set
var q = instance_place_flags(x, y, obj_some, Flag.A|Flag.B, -1, 0);

// finds an instance with both Flag.A set and Flag.B not set
var q = instance_place_flags(x, y, obj_some, Flag.A|Flag.B, Flag.A, 0);

// finds an instance with Flag.A or Flag.B set
var q = instance_place_flags(x, y, obj_some, Flag.A|Flag.B, 0, 1);
instance_flags_ordered

Determines whether results returned by instance flags functions should be ordered ("ordered" argument in collision_list functions)

instance_number_flags(obj, flags, value, not)number

Returns the number of instances matching a flag query.

You can then pick through them using instance_find_flags or instance_find_flags_all.