Thermo is the Domain Specific Language (DSL) for [cyberspace](https://github.com/arkin0x/cyberspace/) that enables the creation of interactive 3D experiences.

Thermo is interpreted by a cyberspace client via a language-specific binding such that Thermo is executed consistently regardless of the underlying execution environment that the client is operating on.

STATUS: DRAFT

---

A Shard is a kind 33332 [nostr events](https://github.com/nostr-protocol/nostr) that contains Thermo code in the `content` property.

Shards exist within _Constructs_. A Shard MUST include exactly one `e` tag of a _Construct_ ID to indicate which Construct it exists within.

A _Construct_ is an owned cubic region of cyberspace. The Construct serves as a 3D boundary and sandboxed global codespace for all shards and Thermo code within it. A Construct is a Kind 332 event.

A Shard MAY also define its own boundary in the form of a 3D box that exists within the bounding box of its encapsulating Construct.

The Shard boundary is distinct from the shard's _geometry_; the shard's geometry can be acted on by Thermo code to manipulate it within its boundary.

Thermo code may be scoped to the shard (local) or construct (global).

## Thermodynamics

All actions in cyberspace require proof-of-work. When creating experiences, properly structured proof-of-work requirements can replace the need for permissions in certain contexts.

Thermo allows you to define Actions, which are functions that can be triggered by Avatars within shards, and set the [NIP-13 proof-of-work](https://github.com/nostr-protocol/nips/blob/master/13.md) requirements of those actions. The minimum unit of proof-of-work for any action is 1. There is no default maximum proof-of-work for an action but a maximum may be set. Actions may be available to participants based on conditions, such as the participant's current coordinate location, or some other value within the construct. Actions are triggered by publishing a Shard Action kind 332 event to one's action chain that contains the necessary proof-of-work and action parameters.

By including shard actions in your cyberspace action chain, your honesty about the timing of your events within a construct is tied to your honesty about your presence in cyberspace. This means that the [consequence for cheating](https://github.com/arkin0x/cyberspace/blob/master/readme.md#aggression) in a Construct are the same as cheating elsewhere in cyberspace.

## Abstracted Experiences

Any experience composed of shards in a construct is essentially an abstraction to the reality of cyberspace. Just as a board game that you play with your friends is an abstraction within reality, construct-based experiences do not have consequences outside of them. In terms of the base mechanics of cyberspace, shards have no effect on one's Avatar. Shards can't push or pull or Derezz you.

However, shards may represent proxy presences for avatars, and Thermo will provide tools so that an Operator may temporarily embody a shard instead of their avatar for the sake of participating in a construct experience. For example, Thermo will allow you to transmit your camera view into a shard that represents your playable character in an experience; this will disconnect your camera view from your avatar temporarily as you play the game.

Your avatar is always present in cyberspace even if you are disconnect from it, and it is still vulnerable. However, there are other cyberspace mechanics and client features that can help protect avatars while they are dormant during experiences.

It is actually better for a Construct experience to utilize these aformentioned proxy shards as playable characters rather than avatars, because shards cannot influence avatars. If the experience has special rules about how a player must interact with an object or move within a space, those rules cannot be enforced on an avatar because the avatar is only subject to the physical rules of cyberspace, but a shard may be completely subject to the local rules. These rules that govern shards are expressed in Thermo.

Shards may represent non-player entities that still require proof-of-work to operate. In this case, the proof-of-work may be supplied by the construct owner, a defined set of participants, or anyone, and there may be consequences for not contributing the necessary proof-of-work to power the entity, such as a lose condition on a game. An analogy for this would be two players competing in an online game but also supplying power to the online game's server in equal amounts; if one player does not supply their share, they lose the game automatically.

### RNG

When an experience needs random entropy, the event id on supplied proof-of-work can be used for this purpose.

## Actions

Actions are like functions that may be triggered by any avatar that meets the action's conditions. Here is some simple example Thermo code you could find within a Shard that allows an operator to execute a kick action on a ball.

name ball

construct bounds action kick 1:
    ball.geometry.vel3 = unit(ball.geometry.vec3 - op.vec3) * pow

Let's break this down:

`name ball` assigns the name `ball` to the current Shard. Recall that all Thermo code is written within a Shard event's `content` tag. If this statement was missing, the Shard could not be referenced in its own code nor in other Shards' code.

`construct bounds` means that this action may be activated by any operator within the construct bounds.

`action kick` simply means we are defining an action named `kick`.

`1:` is the proof-of-work requirement to call the action. The format is minimum:maximum. In this case, the minimum is 1 and the maximum is unbounded. A proof-of-work requirement could be written as simply `:` to mean `1:unbounded`, as 1 unit is always the minimum.

Note the Python-like indentation syntax for action definitions.

In the action body, we are setting the velocity of the ball's geometry equal to the unit vector of the displacement vector between the operator (`op`) and the ball, and this unit vector is multiplied by the proof-of-work.

`op` and `pow`, `powmin`, and `powmax` are reserved words that are available in every action.

## Reactions

Reactions are methods that run based on a condition and not in direct response to an avatar's shard action.

We will add to our example code above and make our ball bounce off its bounding box walls:

name ball

construct bounds action kick 1:
    ball.geometry.vel3 = unit(ball.geometry.vec3 - op.vec3) * pow

ball.geometrybounds |> ball.bounds as hit react bounce
    ball.geometry.vel3 = ball.geometry.vel3 * ones(-hit)

Let's break this down.

`ball.geometrybounds` is a reference to the bounding box calculated based on the geometry of the ball shard.

`|>` is the collision exit operator. More on this in a second.

`ball.bounds` is the shard's bounding box.

The collision exit operator returns a vec3 indicating the dimension where the lefthand operand has exited the righthand operand. If the ball is fully within the shard bounds, `|>` will not react (method is not triggered). But for example if the ball exits the right side of the shard bounds, `|>` will trigger a reaction and assign the vec3 `(1.5,0,0)` to `hit`, if the ball has gone 1.5 units beyond the right boundary (left/right means x axis).

`as hit` puts the result of the collision exit operator into a variable called `hit`.

`react bounce` gives the name `bounce` to the reaction.

Next the code of the reaction will be executed.

`ball.geometry.vel3` velocity is set to a new value via `=`.

`ball.geometry.vel3 * ones(-hit)` is doing a few things:

- `hit` is a vec3 whose value comes from the collision exit operator. It will be all zeroes except for the axes on which the first operand exited the second; the nonzero values are in cyberspace units.
- `-hit` will multiply each value in the vec3 by `-1`. Zeroes are unaffected, naturally.
- `ones(-hit)` The `ones` function will change any 0s to 1s.
- The `ball.geometry.vel3` velocity is multiplied by the resulting vec3. The effect is that the velocity is reversed in the direction that collided with the bounding box wall, creating a bounce effect.

### Interactions Between Shards

Goal shard

name goal

ball.geometrybounds <| goal.bounds react score
	player1.score += 1

Player shard

name player1

alloc score: Uint8 = 0

Game shard

name soccergame

alloc playing: boolean = true

## Code Complexity

Because the predominant context for Thermo is operating on 3D space, there is a lot of convenience and abstraction around making 3D calculations. This is great because the complexity of your Thermo code imposes a cost on its publication based on the number of tokens it contains.

Thermo code can be broken into tokens using the following function:

# js
export function tokenize(str) {
  let tokens = [];
  let currentToken = '';

  // Track indentation level
  let indent = 0;

  const separators = ['(', ')', ':', '\n'];
  const operators = ['+', '-', '*', '/', '%', '<|', '|>', '&&', '||', '==', '!=', 'is', 'and', 'or'];

  for (let char = 0; char < str.length; char++) {
    
    const c = str[char];
    // Handle whitespace and indentation
    // if the previous character was a newline and the current character is one or more spaces, treat it as an indentation.
    if (c === ' ') {
      if (currentToken) {
        tokens.push(currentToken);
        currentToken = '';
      }
    }
    else if( c === '\t') {
      indent++;
    }
    else if (c === '\n') {
      if (currentToken) {
        tokens.push(currentToken);
        currentToken = '';  
      }
      // check if whitespace is following a newline
      if ( str[char+1] === ' ' ) {
        console.log(char, 'looking for indentation')
        // use the number of spaces to determine the indentation level
        indent = 0;
        let lookahead = 0
        while ( str[char+lookahead+1] === ' ' ) {
          console.log('+1')
          indent++;
          lookahead++;
        }
        indent = Math.ceil(indent/4)
      }
      tokens.push({type: 'NEWLINE', indent: indent});
      indent = 0;
    }

    // Handle separators  
    else if (separators.includes(c)) {
      if (currentToken) {
        tokens.push(currentToken);
        currentToken = '';
      }
      tokens.push(c);
    }
    
    // Handle operators
    else if (operators.includes(c)) {
      if (currentToken) {
        tokens.push(currentToken);
        currentToken = '';
      }
      tokens.push(c);
    }
    
    // Accumulate alphanumerics into tokens
    else {
      currentToken += c;
    }
  }

  if (currentToken) {
    tokens.push(currentToken);
  }

  return tokens;
}

The ceiling of the square root of the number of tokens in a Thermo script is the amount of proof-of-work the shard requires to be considered valid.

Shards also require separate proof-of-work proportional to their mesh data (vertices and materials) but these have not yet been defined.

# License

https://creativecommons.org/licenses/by-sa/4.0/legalcode