ADR-255: Texture tweens

More details about this document
Latest published version:
https://adr.decentraland.org/adr/ADR-255
Authors:
nearnshaw
Feedback:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on githistory.xyz

Abstract

This document describes an approach for making it possible for creators to animate textures. This can be used to simulate running liquids, as well as many other interesting texture effects.

This new feature combines very well with ADR-254 (GLTF Nodes), as it enables to do the same effects on the textures of any .gltf model.

Offset and tiling

Today the settings available on a texture are limited. We need to be able to also change the offset and the scale of a texture. As part of this ADR we're also adding two new fields to all textures:

A creator could theoretically write a system that changes the offset value on every frame, but that would be very bad for performance. If something will continually change their offset, it's recommended to instead use a Tween for that.

Texture tween

We'll define a new type of tween that affects the Material rather than the Transform. This is enabled by using the already existing Tween and TweenSequence components, with a new TextureMove option to be added to the existing Move, Rotate, and Scale.

The new TextureMove option on the Tween component will have the following fields:

The scene can also use a TweenSequence to make continuos movements possible, just like with other kinds of tweens.

Texture layers

Materials have several textures besides the albedo_texture, including bump_texture, alpha_texture, emissive_texture. The TextureMove Tween affects the base texture, so all textures move together with it.

This applies to changing the offset and tiling fields manually, as well as using a texture tween.

Serialization

parameters:
  COMPONENT_ID: 1102
  COMPONENT_NAME: core::Tween
  CRDT_TYPE: LastWriteWin-Element-Set
message Texture {
  string src = 1;
  optional TextureWrapMode wrap_mode = 2; // default = TextureWrapMode.Clamp
  optional TextureFilterMode filter_mode = 3; // default = FilterMode.Bilinear

  // Final uv = offset + (input_uv * tiling)
  optional Vector2 offset = 4; // default = Vector2.Zero; Offset for texture positioning, only works for the texture property in PbrMaterial or UnlitMaterial.
  optional Vector2 tiling = 5; // default = Vector2.One; Tiling multiplier for texture repetition, only works for the texture property in PbrMaterial or UnlitMaterial.
}

message PBTween {
  float duration = 1; // in milliseconds
  EasingFunction easing_function = 2;

  oneof mode {
    Move move = 3;
    Rotate rotate = 4;
    Scale scale = 5;
    TextureMove texture_move = 8;
  }

  optional bool playing = 6; // default true (pause or running)
  optional float current_time = 7; // between 0 and 1
}

// This tween mode allows to move the texture of a PbrMaterial or UnlitMaterial.
// You can also specify the movement type (offset or tiling)
message TextureMove {
  decentraland.common.Vector2 start = 1;
  decentraland.common.Vector2 end = 2;
  optional TextureMovementType movement_type = 3; // default = TextureMovementType.TMT_OFFSET
}

enum TextureMovementType {
  TMT_OFFSET = 0; // default = TextureMovementType.TMT_OFFSET
  TMT_TILING = 1;
}

Semantics

Example

Offset texture:

Material.setPbrMaterial(myEntity, {
  texture: Material.Texture.Common({
    src: "assets/materials/wood.png",
    wrapMode: TextureWrapMode.TWM_REPEAT,
    offset: Vector2.create(0, 0.2),
    tiling: Vector2.create(1, 1)
  })
})

Simple continuos flow:

const myEntity = engine.addEntity()

MeshRenderer.setPlane(myEntity)

Transform.create(myEntity, {
  position: Vector3.create(4, 1, 4)
})

Material.setPbrMaterial(myEntity, {
  texture: Material.Texture.Common({
    src: "materials/water.png",
    wrapMode: TextureWrapMode.TWM_REPEAT
  })
})

Tween.create(myEntity, {
  mode: Tween.Mode.TextureMove({
    start: Vector2.create(0, 0),
    end: Vector2.create(0, 1)
  }),
  duration: 1000,
  easingFunction: EasingFunction.EF_LINEAR
})

TweenSequence.create(myEntity, { sequence: [], loop: TweenLoop.TL_RESTART })

Square-moving tween sequence:

//(...)

Tween.create(myEntity, {
  mode: Tween.Mode.TextureMove({
    start: Vector2.create(0, 0),
    end: Vector2.create(0, 1)
  }),
  duration: 1000,
  easingFunction: EasingFunction.EF_LINEAR
})

TweenSequence.create(myEntity, {
  sequence: [
    {
      mode: Tween.Mode.TextureMove({
        start: Vector2.create(0, 1),
        end: Vector2.create(1, 1)
      }),
      duration: 1000,
      easingFunction: EasingFunction.EF_LINEAR
    },
    {
      mode: Tween.Mode.TextureMove({
        start: Vector2.create(1, 1),
        end: Vector2.create(1, 0)
      }),
      duration: 1000,
      easingFunction: EasingFunction.EF_LINEAR
    },
    {
      mode: Tween.Mode.TextureMove({
        start: Vector2.create(1, 0),
        end: Vector2.create(0, 0)
      }),
      duration: 1000,
      easingFunction: EasingFunction.EF_LINEAR
    }
  ],
  loop: TweenLoop.TL_RESTART
})

License

Copyright and related rights waived via CC0-1.0. Draft