Working With...Aspects

Aspect is the term we use for the parts of an asset that holds other assets, whether that's a surfaces or a container. Our primary five* aspects are: in, on, under, behind, attached. Any tangible asset can have aspects. For example, a pot might have an in aspect, which contains water. A table might have an on aspect, which holds papers. All rooms have an in aspect, which holds everything in the room, including the player. Assets can also have multiple aspects. For example, a bed might have an on aspect and also an under aspect. In short, aspects are how we put things in things.

* Aspects aren't limited to the core five. For example you might create an over aspect to provide a response to player input like look over wall.

Aspect Basics

Here's the very minimum needed to define an aspect. Most built-in asset classes already have aspects defined, but you never know when you'll want to create your own.

MyGame.createAsset({
    class: "Chest",
    name: "treasure chest",
    place: "Treasure Room",
    aspects: { in: true },
});

By setting aspects: { in: true }, we're creating an in aspect that we can put other assets in. Here's how to put another asset in an aspect.

MyGame.createAsset({
    class: "Gem",
    name: "diamond",
    place: {in: "treasure chest"},
  });

There are a couple of alternative shortcuts to place: {in: "treasure chest"} that you may use if you find them easier.

MyGame.createAsset({
  class: "Gem",
  name: "diamond",
  // if no aspect is specified, use the treasure chest's default aspect
  place: "treasure chest",
});

MyGame.createAsset({
  class: "Gem",
  name: "ruby",
  // this only works for the five primary aspects: in, on, under, behind, attached
  in: "treasure chest",
});

If you use place: "treasure chest" without specifying an aspect, the asset will be placed in the default aspect of the target asset. In this case, it's possible that you might need to specify the target's default aspect.

MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  default_aspect: "in",
});

If you try to place an asset in an aspect that doesn't exist on its target, one will be created during game startup.

Aspect Settings

In the example above where we set aspects: { in: true }, we're creating an in aspect with default settings. An aspect's settings allow you to control these properties:

What assets can be placed in the aspect [More info...]

Expand for example

We can specify only the particular assets we want to allow in this aspect.

MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      accepts_assets: [ "ruby", "diamond", "emerald" ],
    } 
  },
});

What classes can be placed in the aspect [More info...]

Expand for example

We can specify only certain classes we want to allow in this aspect.

MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      accepts_classes: [ "Gem", "Coin" ],
    } 
  },
});

What assets can't be placed in the aspect [More info...]
Expand for example

We can specify particular assets that are not allowed in this aspect, so for instance if we wanted it to accept class Gem, but not certain gems.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      excludes_assets: [ "coal", "stone" ],
    } 
  },
});
```
What classes can't be placed in the aspect [More info...]
Expand for example

We can specify certain classes we want to exclude from this aspect. Let's say we don't want anything Edible being placed in this chest.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      excludes_classes: [ "Edible" ],
    } 
  },
});
```
What limits the capacity of the aspect, including height, width, depth, quantity, and weight [More info...]
Expand for example

We can specify capacity limits for assets placed in this aspect. For each property, -1 means infinite, aka no limits. These limits control what the player can put into the aspect, but not what the author can put in.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      capacity: { 
        height: 2,
        width: 4,
        depth: 3,
        count: 20,
        weight: 100,
       },
    } 
  },
});
```
Whether the contents of the aspect are listed in the room description [More info...]
Expand for example

Limit what's included in the room description. This is useful for things that are baked into the room description. For example, imagine a typewriter on a desk that is included in the room description, so that you don't want it listed among the room's inventory.
```
MyGame.createAsset({
  class: "Desk",
  name: "office desk",
  place: "Accounts Office",
  description: "The desk is dominated by an old Corona typewriter. "
  aspects: { 
    on: {
      list_contents_in_room: false,
    } 
  },
});
MyGame.createAsset({
  class: "Typewriter",
  name: "Corona typewriter",
  on: "office desk",
});
```
Whether the contents of the aspect are listed when a player examines the asset [More info...]
Expand for example

Limit what's included when the player examines the asset. By default, examining an asset also list its contents, but there may be cases where you don't want that behavior, such as when nested assets are attached to the main asset and already mentioned in the asset description, like this desk/bench combo.
```
MyGame.createAsset({
  class: "Desk",
  name: "student desk",
  place: "Classroom",
  description: "It's an old-fashioned lift top school desk with an attached bench."
  aspects: { 
    attached: {
      list_contents_in_examine: false,
    } 
  },
});
MyGame.createAsset({
  class: "Chair",
  name: "bench",
  place: { attached: "student desk" },
});
```
Whether the contents of the aspect become known when the player knows the asset [More info...]
Expand for example

By default, when an asset becomes known to a player, its contents also become known (unless inside a closed container). You might not want nested assets known until the player examines the asset.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      know_contents_with_parent: false,
    } 
  },
});
```
Whether the contents of the aspect become seen when the player sees the asset [More info...]
Expand for example

By default, when an asset is seen by a player, its contents also become seen (unless inside a closed container). You might not want nested assets seen until the player examines the asset.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      see_contents_with_parent: false,
    } 
  },
});
```
Whether the player can add assets to the aspect [More info...]
Expand for example

By default, players can add objects to aspects, unless limited by other options, but that can be disabled with this option.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      player_can_add_assets_to_contents: false,
    } 
  },
});
```
Whether the player can remove assets from the aspect [More info...]
Expand for example

By default, players can remove objects from aspects, unless limited by other options, but that can be disabled with this option. This is useful for attached assets, such as the drawers of a desk.
```
MyGame.createAsset({
  class: "Chest",
  name: "treasure chest",
  place: "Treasure Room",
  aspects: { 
    in: {
      player_can_remove_assets_from_contents: false,
    } 
  },
});
```
Whether the aspect is horizontal or vertical [More info...]
Expand for example

Aspect orientation is horizontal by default, but can be set to vertical. Currently this has no impact on aspect contents, but it may in the future.
```
MyGame.createAsset({
  class: "Tree",
  name: "giant redwood",
  place: "Muir Woods",
  aspects: { 
    on: {
      orientation: "vertical",
    } 
  },
});
```
Whether the player can enter the aspect [More info...], also see Working with Nests
Expand for example

Players can't automatically enter aspects. Add a nest to allow a player to enter an aspect. For instance, a bathtub might need a nest so a player can enter it, but a bathroom sink probably would not. Nests have their own set of properties for managing how players can interact with them. [More info...]
```
MyGame.createAsset({
  class: "BasicBathtub",
  name: "obsidian tub",
  place: "Bathroom",
  aspects: { 
    in: {
      aspects: { in: { nest: { can: { enter: true } } } }
    } 
  },
});
```
Whether the aspect can contain substances [More info...], also see Working with Substance Vessels
Expand for example

Aspects don't automatically handle substances. They need a Vessel attached to them. Vessels have their own set of properties for managing contents and quantities. [More info...]
```
MyGame.createAsset({
  class: "DrinkingGlass",
  name: "water glass",
  place: "Bathroom",
  aspects: { 
    in: {
      vessel: { volume: 250, substance_id: "water" },
    } 
  },
});
```

If an author tries to create an aspect on a class that already has one, the existing aspect will be used, but any settings set by the author will be applied to it.

Further Reference

Asset.isAspect() Functions in Author's Manual
Aspect class in Reference Manual