Denizen Script Language Explanations

Language Explanations explain components of Denizen in a more direct and technical way than The Beginner's Guide.

Showing 1 out of 81 language explanations...
NameFlag System
DescriptionThe flag system is a core feature of Denizen, that allows for persistent data storage linked to objects.

"Persistent" means the data is still around even after a server restart or anything else, and is only removed when you choose for it to be removed.
"Linked to objects" means rather than purely global values, flags are associated with a player, or an NPC, or a block, or whatever else.

See also the guide page at 🔗

For non-persistent temporary memory, see instead Command:define.
For more generic memory options, see Command:yaml or Command:sql.

Flags can be sub-mapped with the '.' character, meaning a flag named 'x.y.z' is actually a flag 'x' as a MapTag with key 'y' as a MapTag with key 'z' as the final flag value.
In other words, "<server.flag[a.b.c]>" is equivalent to "<server.flag[a].get[b].get[c]>"

Server flags can be set by specifying 'server' as the object, essentially a global flag target, that will store data in the file "plugins/Denizen/server_flags.dat"

Most unique object types are flaggable - refer to any given object type's language documentation for details.

Most flag sets are handled by Command:flag, however items are primarily flagged via Command:inventory with the 'flag' argument.
Any supported object type, including the 'server' base tag, can use the tags
Tag:FlaggableObject.flag, Tag:FlaggableObject.has_flag, Tag:FlaggableObject.flag_expiration, Tag:FlaggableObject.list_flags.

Additionally, flags be searched for with tags like Tag:server.online_players_flagged, Tag:server.players_flagged, Tag:server.spawned_npcs_flagged, Tag:server.npcs_flagged, ...
Flags can also be required by script event lines, as explained at Language:Script Event Switches.
Item flags can also be used as a requirement in Command:take.

Note that some internal flags exist, and are prefixed with '__' to avoid conflict with normal user flags.
This includes:
- '__raw' and '__clear' which are part of a fake-flag system used for forcibly setting raw data to a flaggable object,
- '__scripts', '__time', etc. which is where some object-type flags are stored inside of server flags,
- '__interact_step' which is used for interact script steps, related to Command:zap,
- '__interact_cooldown' which is used for interact script cooldowns, related to Command:cooldown.

Flags have an expiration system, which is used by specifying a time at which they should expire (or via a duration which internally calculates the date/time of expiration by adding the duration input to the current date/time).
Expirations are then *checked for* in flag tags - meaning, the flag tags will internally compare a stored date/time against the real current date/time,
and if the flag's expiration time is in the past, the flag tag will return values equivalent to if the flag doesn't exist.
There is no system actively monitoring for flag expirations or applying them. There is no event for expirations occurring, as they don't "occur" per se.
In other words, it is correct to say a flag "is expired" or a flag "is not expired",
but it is incorrect to say a flag "expires", as it is not an active action (though this wording can be convenient when speaking informally).
Expired flags are sometimes 'cleaned up' (meaning, any expired flags get actually removed from internal storage), usually when a flag save file is loaded into the server.

As a bonus feature-combo, it is possible to transmit sets of flags exactly in-place and reapply them, this is particular useful for example to synchronize player data across Bungee servers.
To do this, you can read raw flag data with the tag Tag:FlaggableObject.flag_map and the '__raw' prefix in a flag command. For example:

# Gather the original data
- define playerdata <player.flag_map[flag1|flag2|taco|potato|waffle|etc]>
# Now reapply it elsewhere (eg a different Bungee server)
- flag <player> __raw:<[playerdata]>
GroupDenizen Scripting Language