Housing Update - Variables, Action Improvements, and more!

housing-apr25.png

Hey!

Today, we're releasing a Housing update with some of the most highly requested features from the community! This update includes:
  • Variables
  • Action Improvements
  • Player State Control
  • House Analytics
  • Leaderboard Improvements
  • and more!
Continue reading to learn more!

► Variables

Ever since the implementation of the basic stats system, players have requested the ability to use more types in them, such as strings or numbers with decimal places. This update focuses on reworking the stats system from the ground up to support multiple types! We're also renaming the system from "Stats" to "Variables", as it fits a lot better with the more general nature of the feature.

While this section gets quite deep and technical around the changes, it's worth noting that we've tried to make things as simple as possible for creators who are already used to using stats, so it should be a small learning curve to be able to utilise the newly added types.

Due to the length of this section, we've thrown it in a spoiler. So if you're interested in all the detailed changes around stats/variables then feel free to read the spoiler!
  • Variables now have type support, with the addition of doubles and strings along with the previous type of longs.
    • When a variable value is set, its type is inferred based on the user input.
      • Any number value will be parsed as the relevant number, whole numbers becoming a long (the type used for stats previously), and any decimal values becoming a double.
        • 500 will become a long.
        • 500.5 will become a double.
        • If you wish to force a specific number type, you can provide a suffix with a L or D, so 500D will be a double.
      • Any value in quotes will be parsed as a string, for example, "hello" or "500" will both be parsed as a string.
      • Any value that does not fit into the above will automatically be handled as a string.
        • Note that there is a length limit to strings; this limit is currently 32 characters.
    • Variables cannot change types, so any operation that modifies an existing value, such as an increment, will require that both values used in the operation be the same type.
      • When setting a variable this is not an issue, as a set operation will simply override the existing value.
  • Unlike previously with stats, variables by default will not unset their values, even if the values are considered a default value, such as zero for numbers.
    • This is due to the fact that even values of zero, will still need to be stored to keep reference to which type is used.
    • The Change Variable action has a new mode option to unset variables, as documented further below.
    • The Change Variable action also has a setting to automatically unset values if they do become their default.
  • Variables do support using placeholders to modify their values, however, the above restrictions still apply with regard to types.
    • Some placeholders may be different when passed into a variable, for example, the player name placeholder will use the nickname of the player when required when used with variables.
  • Stats and Variable limits are now handled by a storage limit rather than a fixed amount limit due to the nature of different variables taking up varying amounts of space.
    • The base storage limit is 512 bytes per holder.
      • This means each unique player has 512 bytes available to them for variables, same for each unique team, and the global house variables. Note that player states are stored separately and do not count toward this limit.
    • This limit is multiplied by 5x for Housing+ owners, the same as the previous limit.
    • The contribution to the limit is based on the type:
      • Longs are stored in the smallest size possible based on the value; this can range from 1 to 8 bytes.
        • For example, a long that is the value 10,000 would be able to fit in 2 bytes.
      • Doubles are always stored as an 8-byte value to allow maximum precision.
      • Strings are dynamic based on the contents of the string, however, most strings will be 1 byte per character.
    • When using only longs (the same as the old stats system), this limit is slightly over 50% greater than before and would hold 64 long values.
      • However, since numbers below specific amounts are smaller, this real-world limit is much greater for most houses. As an example, if you only use numbers below 2.1 billion, these will use 4 bytes each, leading to 128 total number stats.
    • The old logic for handling stat limit overflow has been removed. Stat limits are now hard enforced, with errors being thrown if these limits are reached for a single holder. You can learn more about this in the actions section later in this post.
  • A new action has been added to replace the 3 previous stat actions, this is the "Change Variable" action.
    • This action allows changing the variable for any variable holder, including the player, the player's team, another team, or the house.
    • The following settings are available for this action:
      • Holder
        • The target holder for which data you wish to modify, this can be the player, a team, or the global variables/house.
      • Team
        • If the team holder is selected, you can select a specific team or use the team of the player who invokes the action.
      • Variable
        • The key of the variable you wish to modify.
      • Mode
        • The way you wish to modify the variable, including a new "Unset" option, which will completely unset the variable from the holder.
      • Value
        • The value to use for the above modification, such as the number to increment by.
        • This value supports placeholders, including placeholders that contain strings for when setting a string variable.
      • Automatic Unset
        • When enabled, any time a stat is considered a "default" value, such as a zero for numbers, or an empty string, it will be automatically unset from the holder.
        • This setting primarily exists to maintain previous behaviors that would consider stats of zero to be unset.
    • The existing actions for modifying stats of players, teams, and globally have been removed, and any existing uses of these stats should be automatically migrated upon loading to the new action with the same settings and behavior as before.
  • New placeholders for variables have been added; they are similar to the previous stat placeholders but have some differences:
    • Because variables have multiple types, there is no default for a variable that doesn't exist. As a result, a variable placeholder without a fallback for a variable that doesn't exist will provide no output.
    • Placeholders for variables allow providing a fallback value, for example, you can use the placeholder %var.player/quest None!%, and when the quest variable does not exist, it will display None!instead.
      • Note that you can provide a fallback value in quotes if you wish to include spaces, for example %var.player/quest "No quest!"%
    • The old stat placeholders will continue to function, but will only function with long types, as that is what they were handled as previously. We recommend creators to start using the new placeholder, although we have no plans to fully remove the stats placeholder at this time.
  • Many actions and conditions now support doubles where possible, such as when handling player health.
  • Variables for players, teams, and the house, can be modified using the new /variables command. The older stat commands currently function, but only for longs, and will be phased out in the future.

► Actions

Actions now have additional functionality for feedback on actions that have been executed, including the ability to throw errors and provide warnings where necessary.
  • Errors:
    • Errors are considered severe and will halt all execution of that action and any subsequent actions as part of that group.
      • For example, if an error occurs in a function inside a button, the execution of all actions for that button press will stop.
    • An example of an action error would be hitting the stats/variables limit, or something unexpectedly going wrong in the execution.
    • For this update, we've tried to avoid moving existing functionality that would quietly fail into these errors to avoid impacting existing houses.
  • Warnings:
    • Warnings are for situations where we feel an error is not required or for existing behavior that we didn't want to change for existing houses.
    • Warnings are simply displayed to the house owner when executed on them or accessible via the recent action logs command as documented further down.
    • An example of a warning would be a location setting that resolves to an invalid destination, such as being outside of the plot.
Errors will notify the player that an error occurred. If an error or warning occurs to the House owner, they will be given extra information regarding the error. Previous errors can also be accessed via the /housing logger command and will give some extra context on hover when possible. This command is currently limited to the last 10 entries for the house.

1744296857339.png

1744296878418.png

► Setting Summaries

This update also includes improvements to the way settings are displayed for actions, conditions, and scoreboard lines. With this, you can now see a quick preview of the settings for that specific element:

1744296963992.png

► Action Notes

You can now leave notes on any actions, this allows you to document behavior of the action and leave notes for yourself for future reference. Actions that have settings will have a notes element at the bottom of the menu, you can also leave notes on any action by using the Drop Key from the Edit Actions menu.

1745096425152.png

► Player State Control

Player states have been updated with additional data, as well as the ability to toggle specific types of data that should be saved and loaded from stored player states. These settings can be found under the Player Data option in House Settings.

1745417230569.png

The available states as of this update are as follows:
  • Location
    • Current Location
    • Current Flight Status NEW
  • Parkour
    • Active Parkour Progress
  • Health
    • Current Health
    • Current Max Health
    • Current Food Level NEW
  • Inventories
    • Player Inventory + Armor
    • Ender Chest Contents
    • Held Item Slot
  • Potion
    • Active Potion Effects NEW
    • Note: This state is not enabled by default on pre-existing houses to preserve existing behavior.
  • Team
    • Current Player Team
As before, a House reinstancing will persist in all the above states regardless of the settings within the player states menu.

► House Analytics

With this update we're also introducing our first iteration of the House Analytics feature. As of today this feature will allow you to view the total of unique players that have joined your house over a specific time period, those being daily, weekly, monthly, yearly, and all time. The current analytics system has been tracking data since the start of April, so all analytics should be correct since then.

This new feature can be accessed via the Systems menu for anyone with the newly added "View Analytics" group permission.

1745417568711.png

In the future, we hope to explore additional analytics and functionality around this system where possible, so we're open to ideas and feedback regarding this.

► Leaderboard Improvements

With this update, we've also reworked the way leaderboards function to heavily improve the customizability and feature set! Similar to the changes made to the actions in this update, the two different types of leaderboards have been merged into a single leaderboard entity for simplification.

This new leaderboard entity allows you to select from a few different options for their data provider:
  • Player Parkour Time
    • This is the equivalent of the previous Parkour Leaderboard.
  • Player Variable
    • This is the equivalent of the previous Stat Leaderboard and is designed to show any number variable.
  • Team Variable
    • This is a new data provider and allows the ability to show teams on a leaderboard based on a number variable.
Based on the selected data provider, the remaining settings for the leaderboard will change accordingly. These settings are:
  • Variable Key
  • Invert Sorting
  • Show All Entries
    • These 3 options are the same as before, and their behavior is unchanged.
  • Line Count
    • Allows changing the number of lines that are shown on the leaderboard, ranging from 1 to 20.
  • Format Type
    • Allows customizing the format that is used for the value of the entries on the leaderboard.
    • This setting is only supported when a variable data provider is used.
  • Show Personal
    • When enabled, the player's own score will be shown at the bottom of the leaderboard.
    • This setting is only supported when a variable data provider is used.
  • Display Conditions
  • Match Any Condition
    • Allows the ability to use conditions to filter which players should show on the leaderboard.
    • This setting is only supported for the player variable data provider.

► Improvements and Changes
  • The following commands now support tab completion:
    • /gamerule
    • /custommenus
    • /function
    • /command
    • /layout
    • /region
  • Added a new gamerule setting to toggle the inventory bin inventoryBin
    • This setting is disabled by default on new houses; existing houses will have the setting enabled by default.
  • Regions can now have their position relocated via a new element in the edit region menu.
  • Improved reinstancing to wait for the new server to load the world before attempting to send players. This reduces the chance of players timing out while connecting to the new server, especially with larger/complex worlds.
  • Added a new setting under PVP/Damage Settings to toggle natural regeneration.
  • Added an action to change the player's time.
  • Added an action to change the player's weather.
  • Increased the maximum duration for player stats and states from 14 days to 30 days for houses without Housing+.

► Bug Fixes
  • Fixed the portal type condition not functioning
  • Fixed NPCs being spawned with a delay when first placed
  • Fixed an issue causing "Kill/Death Messages" and "Instant Respawn" not being enabled by default with new houses

That's it for this one! We're looking forward to seeing what creators come up with thanks to all these changes!
 
Click to expand...
ConnorLinfoot said:

Hey!

Today, we're releasing a Housing update with some of the most highly requested features from the community! This update includes:
  • Variables
  • Action Improvements
  • Player State Control
  • House Analytics
  • Leaderboard Improvements
  • and more!
Continue reading to learn more!

► Variables

Ever since the implementation of the basic stats system, players have requested the ability to use more types in them, such as strings or numbers with decimal places. This update focuses on reworking the stats system from the ground up to support multiple types! We're also renaming the system from "Stats" to "Variables", as it fits a lot better with the more general nature of the feature.

While this section gets quite deep and technical around the changes, it's worth noting that we've tried to make things as simple as possible for creators who are already used to using stats, so it should be a small learning curve to be able to utilise the newly added types.

Due to the length of this section, we've thrown it in a spoiler. So if you're interested in all the detailed changes around stats/variables then feel free to read the spoiler!
  • Variables now have type support, with the addition of doubles and strings along with the previous type of longs.
    • When a variable value is set, its type is inferred based on the user input.
      • Any number value will be parsed as the relevant number, whole numbers becoming a long (the type used for stats previously), and any decimal values becoming a double.
        • 500 will become a long.
        • 500.5 will become a double.
        • If you wish to force a specific number type, you can provide a suffix with a L or D, so 500D will be a double.
      • Any value in quotes will be parsed as a string, for example, "hello" or "500" will both be parsed as a string.
      • Any value that does not fit into the above will automatically be handled as a string.
        • Note that there is a length limit to strings; this limit is currently 32 characters.
    • Variables cannot change types, so any operation that modifies an existing value, such as an increment, will require that both values used in the operation be the same type.
      • When setting a variable this is not an issue, as a set operation will simply override the existing value.
  • Unlike previously with stats, variables by default will not unset their values, even if the values are considered a default value, such as zero for numbers.
    • This is due to the fact that even values of zero, will still need to be stored to keep reference to which type is used.
    • The Change Variable action has a new mode option to unset variables, as documented further below.
    • The Change Variable action also has a setting to automatically unset values if they do become their default.
  • Variables do support using placeholders to modify their values, however, the above restrictions still apply with regard to types.
    • Some placeholders may be different when passed into a variable, for example, the player name placeholder will use the nickname of the player when required when used with variables.
  • Stats and Variable limits are now handled by a storage limit rather than a fixed amount limit due to the nature of different variables taking up varying amounts of space.
    • The base storage limit is 512 bytes per holder.
      • This means each unique player has 512 bytes available to them for variables, same for each unique team, and the global house variables. Note that player states are stored separately and do not count toward this limit.
    • This limit is multiplied by 5x for Housing+ owners, the same as the previous limit.
    • The contribution to the limit is based on the type:
      • Longs are stored in the smallest size possible based on the value; this can range from 1 to 8 bytes.
        • For example, a long that is the value 10,000 would be able to fit in 2 bytes.
      • Doubles are always stored as an 8-byte value to allow maximum precision.
      • Strings are dynamic based on the contents of the string, however, most strings will be 1 byte per character.
    • When using only longs (the same as the old stats system), this limit is slightly over 50% greater than before and would hold 64 long values.
      • However, since numbers below specific amounts are smaller, this real-world limit is much greater for most houses. As an example, if you only use numbers below 2.1 billion, these will use 4 bytes each, leading to 128 total number stats.
    • The old logic for handling stat limit overflow has been removed. Stat limits are now hard enforced, with errors being thrown if these limits are reached for a single holder. You can learn more about this in the actions section later in this post.
  • A new action has been added to replace the 3 previous stat actions, this is the "Change Variable" action.
    • This action allows changing the variable for any variable holder, including the player, the player's team, another team, or the house.
    • The following settings are available for this action:
      • Holder
        • The target holder for which data you wish to modify, this can be the player, a team, or the global variables/house.
      • Team
        • If the team holder is selected, you can select a specific team or use the team of the player who invokes the action.
      • Variable
        • The key of the variable you wish to modify.
      • Mode
        • The way you wish to modify the variable, including a new "Unset" option, which will completely unset the variable from the holder.
      • Value
        • The value to use for the above modification, such as the number to increment by.
        • This value supports placeholders, including placeholders that contain strings for when setting a string variable.
      • Automatic Unset
        • When enabled, any time a stat is considered a "default" value, such as a zero for numbers, or an empty string, it will be automatically unset from the holder.
        • This setting primarily exists to maintain previous behaviors that would consider stats of zero to be unset.
    • The existing actions for modifying stats of players, teams, and globally have been removed, and any existing uses of these stats should be automatically migrated upon loading to the new action with the same settings and behavior as before.
  • New placeholders for variables have been added; they are similar to the previous stat placeholders but have some differences:
    • Because variables have multiple types, there is no default for a variable that doesn't exist. As a result, a variable placeholder without a fallback for a variable that doesn't exist will provide no output.
    • Placeholders for variables allow providing a fallback value, for example, you can use the placeholder %var.player/quest None!%, and when the quest variable does not exist, it will display None! instead.
  • Many actions and conditions now support doubles where possible, such as when handling player health.

► Actions

Actions now have additional functionality for feedback on actions that have been executed, including the ability to throw errors and provide warnings where necessary.
  • Errors:
    • Errors are considered severe and will halt all execution of that action and any subsequent actions as part of that group.
      • For example, if an error occurs in a function inside a button, the execution of all actions for that button press will stop.
    • An example of an action error would be hitting the stats/variables limit, or something unexpectedly going wrong in the execution.
    • For this update, we've tried to avoid moving existing functionality that would quietly fail into these errors to avoid impacting existing houses.
  • Warnings:
    • Warnings are for situations where we feel an error is not required or for existing behavior that we didn't want to change for existing houses.
    • Warnings are simply displayed to the house owner when executed on them or accessible via the recent action logs command as documented further down.
    • An example of a warning would be a location setting that resolves to an invalid destination, such as being outside of the plot.
Errors will notify the player that an error occurred. If an error or warning occurs to the House owner, they will be given extra information regarding the error. Previous errors can also be accessed via the /housing logger command and will give some extra context on hover when possible. This command is currently limited to the last 10 entries for the house.


► Setting Summaries

This update also includes improvements to the way settings are displayed for actions, conditions, and scoreboard lines. With this, you can now see a quick preview of the settings for that specific element:


► Action Notes

You can now leave notes on any actions, this allows you to document behavior of the action and leave notes for yourself for future reference. Actions that have settings will have a notes element at the bottom of the menu, you can also leave notes on any action by using the Drop Key from the Edit Actions menu.


► Player State Control

Player states have been updated with additional data, as well as the ability to toggle specific types of data that should be saved and loaded from stored player states. These settings can be found under the Player Data option in House Settings.


The available states as of this update are as follows:
  • Location
    • Current Location
    • Current Flight Status NEW
  • Parkour
    • Active Parkour Progress
  • Health
    • Current Health
    • Current Max Health
    • Current Food Level NEW
  • Inventories
    • Player Inventory + Armor
    • Ender Chest Contents
    • Held Item Slot
  • Potion
    • Active Potion Effects NEW
    • Note: This state is not enabled by default on pre-existing houses to preserve existing behavior.
  • Team
    • Current Player Team
As before, a House reinstancing will persist in all the above states regardless of the settings within the player states menu.

► House Analytics

With this update we're also introducing our first iteration of the House Analytics feature. As of today this feature will allow you to view the total of unique players that have joined your house over a specific time period, those being daily, weekly, monthly, yearly, and all time. The current analytics system has been tracking data since the start of April, so all analytics should be correct since then.

This new feature can be accessed via the Systems menu for anyone with the newly added "View Analytics" group permission.


In the future, we hope to explore additional analytics and functionality around this system where possible, so we're open to ideas and feedback regarding this.

► Leaderboard Improvements

With this update, we've also reworked the way leaderboards function to heavily improve the customizability and feature set! Similar to the changes made to the actions in this update, the two different types of leaderboards have been merged into a single leaderboard entity for simplification.

This new leaderboard entity allows you to select from a few different options for their data provider:
  • Player Parkour Time
    • This is the equivalent of the previous Parkour Leaderboard.
  • Player Variable
    • This is the equivalent of the previous Stat Leaderboard and is designed to show any number variable.
  • Team Variable
    • This is a new data provider and allows the ability to show teams on a leaderboard based on a number variable.
Based on the selected data provider, the remaining settings for the leaderboard will change accordingly. These settings are:
  • Variable Key
  • Invert Sorting
  • Show All Entries
    • These 3 options are the same as before, and their behavior is unchanged.
  • Line Count
    • Allows changing the number of lines that are shown on the leaderboard, ranging from 1 to 10.
  • Format Type
    • Allows customizing the format that is used for the value of the entries on the leaderboard.
    • This setting is only supported when a variable data provider is used.
  • Show Personal
    • When enabled, the player's own score will be shown at the bottom of the leaderboard.
    • This setting is only supported when a variable data provider is used.
  • Display Conditions
  • Match Any Condition
    • Allows the ability to use conditions to filter which players should show on the leaderboard.
    • This setting is only supported for the player variable data provider.

► Improvements and Changes
  • The following commands now support tab completion:
    • /gamerule
    • /custommenus
    • /function
    • /command
    • /layout
    • /region
  • Added a new gamerule setting to toggle the inventory bin inventoryBin
    • This setting is disabled by default on new houses; existing houses will have the setting enabled by default.
  • Regions can now have their position relocated via a new element in the edit region menu.
  • Improved reinstancing to wait for the new server to load the world before attempting to send players. This reduces the chance of players timing out while connecting to the new server, especially with larger/complex worlds.
  • Added a new setting under PVP/Damage Settings to toggle natural regeneration.
  • Added an action to change the player's time.
  • Added an action to change the player's weather.
  • Increased the maximum duration for player stats from 14 days to 30 days for houses without Housing+.

► Bug Fixes
  • Fixed the portal type condition not functioning
  • Fixed NPCs being spawned with a delay when first placed
  • Fixed an issue causing "Kill/Death Messages" and "Instant Respawn" not being enabled by default with new houses

That's it for this one! We're looking forward to seeing what creators come up with thanks to all these changes!
Click to expand...
Thank you for the update
 
You must log in or register to reply here.
Back
Top