View source for Spatial variable standards/en

[[Special:MyLanguage/Spatial variables|Spatial Variables]] are a powerful feature allowing you to define location-dependent values. To support seamless interaction between independently developed objects it is necessary to follow standards for naming, types, content and sampling of spatial variables.

This article collects several community-proposed standards made with the goal that other users - instead of creating their own - reuse them for compatibility with other creations.

== Naming Conventions ==

To avoid the risk of naming conflicts it is recommended to follow the naming standard "Prefix.Variable" where a shared prefix groups related variables together.

Using PascalCase would make all future proposals consistent to the existing ones.

== Sampling Mode ==

Standards should recommend a sampling mode where applicable.

Examples include:
* HighestPriority: Only the value with the highest priority is considered. This will lead to abrupt transitions between areas.
* Additive: All variables are added together. Variables with blend distance will avoid sharp transitions. It is not possible to create an area with an override. (priorities are ignored)
* WeightedAverage: All variables are averaged. Variables with blend distance will avoid sharp transitions. It is not possible to create an area with an override. (priorities are ignored)
* PrioritySortedBlend: This layers variables with higher priority on top of variables with lower priority. Variables with blend distance will avoid sharp transitions.

== Default Value ==

Standards should recommend a sensible default value.

Configurable default values can be implemented by using dynamic variables of the "World" space with the same name as the spatial variable. (i.e. dynamic variable "World/Gravity" as a default for the spatial variable "Gravity")

This approach can also be used to extend existing standards for dynamic variables with location-based overrides.

== Official Variables ==

The following variables are defaults used by FrooxEngine:

{| class="wikitable"
|+
!Variable
!Type
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
|Resonite.Audio.Filters
|AudioDSP_Effect
|Sample via the [[Special:MyLanguage/Component:ReferenceSpatialVariableCollector|ReferenceSpatialVariableCollector]]
|audio effects like reverb that are in effect in an area
|Frooxius, 2025
|}

{{Note|As of 2025 spatial variables are a relatively recent feature which means that many of the community-made proposals are still young and may still be under construction. If you see a need for a new standard, feel free to add it to this page! You can discuss your ideas in detail on [https://discord.com/channels/1040316820650991766/1370546052263841924 Discord] or the [[Talk:Spatial_Variable_Standards|Talk Page]].|warning}}

== Simple Interactions ==

The following variables are made to be easily integrated into an object:

{| class="wikitable"
!Variable
!Type
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
!Heat
!float
!Additive
Default: 0
!Positive: heat source
Negative: heat sink
suggested values:
A few meters from a fire: 1
Cooking: 10
Slightly cold: -1
Freezing: -10
!LucasRo7, 2025
|-
!Fire
!bool
!MaxPriority
Default: false
!sets things on fire
!LucasRo7, alizard, Panda, 2025
|-
!Water
!bool
!MaxPriority
Default: false
!puts out fire and makes things wet
!LucasRo7, Panda, 2025
|-
!Electric
!bool
!MaxPriority
Default: false
!shocks things or people, may turn devices on
!LucasRo7, 2025
|-
!Wind
!float3
!Default: [0;0;0]
!wind speed in m/s
!LucasRo7, 2025
|}

== Physical Quantities ==

Temperature, pressure and other values can vary greatly between different locations. (i.e. temperature within fire vs. temperature of an ice cube)

Theoretically every such property could be made a spatial variable.
The following proposals have been created from this idea.

Their usefulness varies: Some, like temperature or gravity, are more prominent in everyday interactions than others. (i.e. electric field)

=== Mature ===

The following proposals have been judged by their author as unlikely to need further changes and/or there are already items using them.

{| class="wikitable"
|+
!Variable
!Type
!Unit
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
|Temperature
<s>(formerly: Physics.Temperature)</s>
|[[Quantity_Types|Temperature]]
|(included in type)
|Mode: PrioritySortedBlend
Default: 
# dynamic variable World/Temperature
# 288.15K / 15°C
|air/water/object temperature
* makes things freeze, boil or ignite
* can be measured with thermometers
* may be required for baking/cooking

Simple games and interactive objects can use the following conditions:
* Freezing water: sampled <= 273.15K / 0°C
* Boiling water (sea level): sampled >= 373.15K / 100°C
* Cooking food: sampled >= 353K / 80°C for X minutes (higher temperature -> faster)
* Starting a fire: sampled >= 550K / 277°C
A typical flame is around 1300K / 1027°C at its core and easily fulfills the requirements to start a fire!

Realistic objects could use "real" temperatures but still be compatible with simplified objects:
* Igniting wood: sampled >= 553-613K / 280-340°C
* Igniting gasoline: sampled >= 493-733K / 220-460°C
* Igniting propane: sampled >= 743K / 470°C
* Wood flame (air): 1300K / 1027°C
* Gasoline flame: 1299K / 1026°C
* Propane flame (air): 1473-1973K / 1200-1700°C
|TheAutopilot, 2025
|-
|Gravity
<s>(formerly: Physics.Gravity)</s>
|float3
|m/s²
|Mode: PrioritySortedBlend
Default:
# dynamic variable World/Gravity
# [0;-9.81;0] m/s²
|global acceleration due to gravity
* accelerate users or items
|TheAutopilot, 2025
|}

=== In Progress ===

The following standards have been suggested by their authors but may need more work and/or adoption in practice.
{| class="wikitable"
|+
!Variable
!Type
!Unit
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
|Physics.Pressure
|float
|Pa
|Default: 101325 Pa
|pressure
* expand or compress hollow objects

Typical pressures for reference:
* sea level: 101325 Pa
* exponential decrease by 50% per 5400m altitude
* every 1m under water: add 9810 Pa
|TheAutopilot, 2025
|-
|Physics.Force
|float3
|N
|Default: [0;0;0] N
|global force applied to all objects within the field
|TheAutopilot, 2025
|-
|Physics.Density
|float
|kg/m³
|Default: 1.225 kg/m³ (air)
|density of the gas/liquid/solid at the sampled position
* detect if within vacuum (breathing)
* compute wind force together with variable "Wind"
|TheAutopilot, 2025
|-
|Physics.ElectricField
|float3
|V/m
|Default: [0;0;0] V/m
Mode: Additive
|vector of the global [[wikipedia:Electric_field|electric field]] at the sampled position
|Papaltine, 2025
|-
|Physics.MagneticField
|float3
|T (Tesla)
|Default: [0;0;0] T
Mode: Additive
|vector of the global [[wikipedia:Magnetic_field|magnetic field]] at the sampled position
* makes a compass point to another direction
|Papaltine, 2025
|-
|Physics.ElectricPotential
|float
|V
|Default: 0 V
|electric potential
* allows measuring voltage between two points
* can be used to check if a user or item should be electrocuted
|TheAutopilot, 2025
|-
|FeetColliders
|Slot list
|NA
|Default: Blank list
|slots that avatar feet should either raycast only, or blacklist these from being raycast.
|989onan, 2025
|-
|FeetCollidersMode
|[[Type:ListFilterMode|ListFilterMode]]
|NA
|Default: BlackList
|Whether feet raycast mode should be black or whitelist.
|989onan, 2025
|}

=== Retracted ===

The following proposals have been retracted by their author. (i.e. in favor of another one)
{| class="wikitable"
|+
!Variable
!Type
!Unit
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
|<s>Physics.Velocity</s>
|<s>float3</s>
|<s>m/s</s>
|<s>Default: [0;0;0] m/s</s>
|<s>global velocity of the gas or liquid at the sampled position
* compute wind force together with density</s>
|<s>TheAutopilot, 2025</s>
(retracted in favor of "Wind" by LucasRo7)
|}

== Location Descriptions ==
{| class="wikitable"
!Variable
!Type
!Sampling Recommendation
!Interpretation
!Proposed by/when
|-
|Location.Tags
|string
|Default: null
|space-separated list of tags describing location
(recommended order: most general to most specific)
Note: Simply checking [[ProtoFlux:Contains|Contains]] may lead to errors with partial matches!
|Redd, 2025
|-
|Location.Slot
|Slot
|Default: null/Root (depends on use-case)
|Slot representing the location a position is in
This can be used to interact with dynamic impulses and dynamic variables.
|TheAutopilot, 2025
|-
|Location.Indoors
|bool
|Default: false
Blending: MaxPriority
|describes whether a location is indoors
|TheAutopilot, 2025
|-
|Location.Underwater
|bool
|Default: false
Blending: MaxPriority
|describes whether a location is underwater
|TheAutopilot,
2025
|}


[[Category:Community standards{{#translation:}}]]