Spatial variable standards: Difference between revisions

From Resonite Wiki
← Older editNewer edit →
VisualWikitext
fixed incorrect spelling of Location.Indoors
added sampling mode and default value recommendations
(11 intermediate revisions by 5 users not shown)
Line 3: Line 3:
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.
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.


== Recommendations ==
== 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.
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.
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 ==
== Official Variables ==
Line 23: Line 39:
|audio effects like reverb that are in effect in an area
|audio effects like reverb that are in effect in an area
|Frooxius, 2025
|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 ==
== Physical Quantities ==
Temperature, pressure and other values can vary greatly between different locations. (i.e. temperature within fire vs. temperature of an ice cube)
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"
{| class="wikitable"
Line 37: Line 114:
!Proposed by/when
!Proposed by/when
|-
|-
|Physics.Temperature
|Temperature
|float
<s>(formerly: Physics.Temperature)</s>
|K
|[[Quantity_Types|Temperature]]
|Default: 288.15 K (= 15°C)
|(included in type)
|temperature (0K = -273.15°C, 273.15K = 0°C)
|Mode: PrioritySortedBlend
Typical temperatures for reference:
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!


* Freezing water: 273.15K (=0°C)
Realistic objects could use "real" temperatures but still be compatible with simplified objects:
* Boiling water (sea level): 373.15K (=100°C)
* Igniting wood: sampled >= 553-613K / 280-340°C
* Igniting wood: 553-613K (=280-340°C)
* Igniting gasoline: sampled >= 493-733K / 220-460°C
* Igniting gasoline: 493-733K (=220-460°C)
* Igniting propane: sampled >= 743K / 470°C
* Igniting propane: 743K (=470°C)
* Wood flame (air): 1300K / 1027°C
* Wood flame (air): 1300K (=1027°C)
* Gasoline flame: 1299K / 1026°C
* Gasoline flame: 1299K (=1026°C)
* Propane flame (air): 1473-1973K / 1200-1700°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
|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
|Physics.Pressure
Line 59: Line 172:
|Default: 101325 Pa
|Default: 101325 Pa
|pressure
|pressure
* expand or compress hollow objects
Typical pressures for reference:
Typical pressures for reference:
* sea level: 101325 Pa
* sea level: 101325 Pa
* exponential decrease by 50% per 5400m altitude
* exponential decrease by 50% per 5400m altitude
* every 1m under water: add 9810 Pa
* every 1m under water: add 9810 Pa
|TheAutopilot, 2025
|-
|Physics.Gravity
|float3
|m/s²
|Default: [0;-9.81;0] m/s²
|global acceleration due to gravity
|TheAutopilot, 2025
|TheAutopilot, 2025
|-
|-
Line 85: Line 192:
|Default: 1.225 kg/m³ (air)
|Default: 1.225 kg/m³ (air)
|density of the gas/liquid/solid at the sampled position
|density of the gas/liquid/solid at the sampled position
|TheAutopilot, 2025
* detect if within vacuum (breathing)
|-
* compute wind force together with variable "Wind"
|Physics.Velocity
|float3
|m/s
|Default: [0;0;0] m/s
|global velocity of the gas or liquid at the sampled position
|TheAutopilot, 2025
|TheAutopilot, 2025
|-
|-
Line 98: Line 200:
|V/m
|V/m
|Default: [0;0;0] V/m
|Default: [0;0;0] V/m
Mode: Additive
|vector of the global [[wikipedia:Electric_field|electric field]] at the sampled position
|vector of the global [[wikipedia:Electric_field|electric field]] at the sampled position
|Papaltine, 2025
|Papaltine, 2025
Line 105: Line 208:
|T (Tesla)
|T (Tesla)
|Default: [0;0;0] T
|Default: [0;0;0] T
Mode: Additive
|vector of the global [[wikipedia:Magnetic_field|magnetic field]] at the sampled position
|vector of the global [[wikipedia:Magnetic_field|magnetic field]] at the sampled position
* makes a compass point to another direction
|Papaltine, 2025
|Papaltine, 2025
|-
|-
Line 112: Line 217:
|V
|V
|Default: 0 V
|Default: 0 V
|electric potential (allows measuring voltage between two points)
|electric potential
* allows measuring voltage between two points
* can be used to check if a user or item should be electrocuted
|TheAutopilot, 2025
|TheAutopilot, 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)
|}
|}


Line 142: Line 270:
|bool
|bool
|Default: false
|Default: false
Blending: MaxPriority
|describes whether a location is indoors
|describes whether a location is indoors
|TheAutopilot, 2025
|TheAutopilot, 2025
|-
|Location.Underwater
|bool
|Default: false
Blending: MaxPriority
|describes whether a location is underwater
|TheAutopilot,
2025
|}
|}

Revision as of 22:07, 30 May 2025

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:

Variable Type Sampling Recommendation Interpretation Proposed by/when
Resonite.Audio.Filters AudioDSP_Effect Sample via the ReferenceSpatialVariableCollector audio effects like reverb that are in effect in an area Frooxius, 2025
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 Discord or the Talk Page.

Simple Interactions

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

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.

Variable Type Unit Sampling Recommendation Interpretation Proposed by/when
Temperature

(formerly: Physics.Temperature)

Temperature (included in type) Mode: PrioritySortedBlend

Default:

  1. dynamic variable World/Temperature
  2. 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

(formerly: Physics.Gravity)

float3 m/s² Mode: PrioritySortedBlend

Default:

  1. dynamic variable World/Gravity
  2. [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.

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 electric field at the sampled position Papaltine, 2025
Physics.MagneticField float3 T (Tesla) Default: [0;0;0] T

Mode: Additive

vector of the global 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

Retracted

The following proposals have been retracted by their author. (i.e. in favor of another one)

Variable Type Unit Sampling Recommendation Interpretation Proposed by/when
Physics.Velocity float3 m/s Default: [0;0;0] m/s global velocity of the gas or liquid at the sampled position
  • compute wind force together with density
 TheAutopilot, 2025

(retracted in favor of "Wind" by LucasRo7)

Location Descriptions

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 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

Retrieved from "https://wiki.resonite.com/index.php?title=Spatial_variable_standards&oldid=103791"
Last modified
This page was last edited on 30 May 2025, at 22:07.