DOCSEARCHbyAlgolia
Submit Docs

@tresjs/cientos

repository·main·Indexed 18 days ago

https://github.com/tresjs/cientos

A collection of useful helpers and ready-made abstractions for TresJS, designed to extend Three.js capabilities within the Vue ecosystem. Version 5.0.0 includes components such as AnimatedSprite for 2D animations, Billboard for camera-facing elements, CubeCamera for environment reflections, Edges for contour highlighting, and Fbo for Frame Buffer Object texture rendering.

Tokens
70.5K
Snippets
243
Records
318
Agent score
62%

What's inside @tresjs/cientos

  1. How Sparkles sequences and mixes work

    main

    Sparkles use a system of Sequences and Mixes to control particle behavior over time or space.

    Sequences (:sequence-* props)

    Sequences define how a property (like color, alpha, or size) changes as a particle "progresses". They use a Gradient<T> type, which can be:

    • A single value: T (e.g., 'red')
    • An even distribution: [T, T, ...] (e.g., ['red', 'blue', 'green'])
    • An uneven distribution with stops: [[number, T], ...] where number is a stop from 0 to 1 (e.g., [[0.1, 'red'], [0.5, 'blue']])

    Mixes (:mix-* props)

    Mixes determine what drives the "progress" through a sequence. A :mix-X prop controls the corresponding :sequence-X prop by interpolating between two factors:

    1. Light Factor (0.0): Progress is determined by how much the vertex normal faces the directionalLight (calculated via the dot product of the inverted light position and the vertex normal).
    2. Lifetime Factor (1.0): Progress is determined by the particle's remaining lifetime.

    Example: Setting :mix-alpha="0.5" means the particle's opacity sequence is halfway between being driven by light and being driven by its age.

    // Example of a sequence and a mix
<Sparkles
  :sequence-color="['red', 'blue', 'green']"
  :mix-color="1.0" // Progress is driven entirely by particle lifetime
/>

  2. Format points for the Line2 component

    main

    The points prop is converted into a flat Array<number> (x, y, z coordinates). You can pass several types of entries, which are interpreted as follows:

    Entry typeInterpretation
    Vector3Insert the vector's x, y, z into the result array
    [number, number, number]Insert the array values into the result array
    Vector2Insert the vector's x, y, then 0 into the result array
    [number, number]Insert the array values, then 0 into the result array
    numberInsert the number into the result array

    Warning: If using bare numbers, you must provide them in triplets (groups of three) to avoid corrupting the coordinate sequence. For example, if you use a [number, number] entry, you must follow it with a number to complete the triplet.

    // ✅ Correct: Every entry results in a triplet (x, y, z)
:points="[[1,1], 2, 2, 0, [3,3]]"
// result: (1,1,0) (2,2,0) (3,3,0)

// ❌ Incorrect: The sequence becomes misaligned
:points="[[1,1], 2, 2, [3,3]]"
// result: (1,1,0) (2,2,3) (3,0,❌)

  3. Use ScreenSizer to scale objects to screen space

    main

    The <ScreenSizer /> component is a <TresObject3D /> wrapper that scales its children to match "screen space". By default, it establishes a ratio where 1 THREE world unit is equivalent to 1 screen pixel.

    For example, if you create a BoxGeometry with dimensions of 100x100x100 and wrap it in a <ScreenSizer />, the box will appear to be exactly 100x100 pixels on the user's screen, regardless of the camera distance or field of view.

    <ScreenSizer>
  <TresBoxGeometry :args="[100, 100, 100]" />
</ScreenSizer>

  4. How to export the entire scene

    main

    To export the entire scene instead of a specific mesh, you can pass the parent property of an object (which is often the scene) to useGLTFExporter.

    Alternatively, you can use the useTresContext composable to access the scene directly. Note that the exact hierarchy depends on your specific scene structure.

    // Using the parent property
const downloadScene = () => {
  useGLTFExporter(boxRef.value.parent)
}

  5. Configure SVG depth handling modes

    main

    The depth option determines how SVG layers are positioned and rendered in 3D space to manage overlapping and z-fighting:

    • 'renderOrder' (Default): Sets materials' depthWrite to false and increments the renderOrder of each layer. Best for lone SVGs, but may cause other scene objects to render out of order.
    • 'flat': Sets materials' depthWrite to false. Simple, but overlapping layers may render in the wrong order depending on perspective.
    • 'offsetZ': Creates a 3D "stack" by adding a small space between each layer. Good for unscaled SVGs seen from the front, but the "bottom" of the stack is visible from behind.
    • number: Similar to 'offsetZ', but allows you to specify the exact spacing (e.g., 0.1) to eliminate z-fighting. Recommended values are between 0.025 and 1.

  6. Choose between useSVG composable and SVG component

    main

    Decide which tool to use based on your requirements for control versus simplicity:

    Use the useSVG composable when you need:

    • Direct access to individual SVG layers.
    • Custom rendering logic.
    • Layer-specific animations.
    • Programmatic geometry manipulation.
    • Advanced material customization per layer.

    Use the <SVG /> component when you need:

    • Simple, declarative SVG rendering.
    • Quick prototyping.
    • Standard SVG display without custom logic.
    • Minimal code and setup.

  7. Generate seeded random lensflare elements

    main

    You can use a pseudorandom number generator (PRNG) to create consistent, repeatable random lensflare elements using seed and seedProps.

    Using seed

    Providing a seed prop allows you to recreate the same random flare pattern. If you set a seed but not seedProps, the component uses built-in default SeedProps[].

    <Lensflare :seed="seedRef" />

    Using seedProps

    The seedProps prop defines the rules for the random generation. Each object in the seedProps array must include:

    • texture: string[] (Required) - Array of 1 or more image URLs.
    • color: TresColor[] (Required) - Array of 1 or more colors.
    • distance: [number, number] (Required) - [min, max] distance from center.
    • size: [number, number] (Required) - [min, max] size.
    • length: [number, number] (Required) - [min, max] number of elements to generate.
    • seed: number (Optional) - A specific seed for this entry's random generation.

  8. Control sprite scaling with the `center` prop

    main

    The center prop serves two purposes:

    1. It sets the anchor point of the sprite (e.g., [0.5, 0.5] is the center).
    2. It controls how differently sized source images grow or shrink. Images will "grow out from" or "shrink towards" the specified center point.
    <AnimatedSprite 
  image="/path/to/texture.png" 
  atlas="/path/to/atlas.json" 
  :center="[0.5, 0.5]" 
/>

  9. How Cientos components work with TresJS

    main
    Cientos is a collection of helpers and components that extend the capabilities of the TresJS core. It uses three-stdlib under the hood. A key feature is that Cientos automatically performs the extend operation for its components, meaning you can use them in your templates immediately after importing them without manual registration.

  10. Use the Sampler abstraction

    main

    The Sampler component is a declarative abstraction that combines MeshSurfaceSampler and InstancedMesh. It works by sampling points from a provided source mesh and then transforming the matrices of an InstancedMesh to distribute its instances across those sampled points.

    To use it, you provide a source mesh to sample from and an InstancedMesh that will receive the distributed instances.

    <Sampler 
  :mesh="sourceMesh" 
  :count="100" 
  :instance-mesh="targetInstancedMesh" 
/>

  12. How to use the useFBO composable

    main

    The useFBO composable allows you to create a Frame Buffer Object (FBO), which is used to render a scene to a texture. This is essential for post-processing effects (like blurring) or for using a rendered scene as a texture in subsequent draw calls.

    Important Requirement: Because useFBO relies on the TresCanvas context, it must be called within a child component of <TresCanvas>. It cannot be used in the same component where <TresCanvas> is defined.

    // Inside a child component of <TresCanvas>
import { useFBO } from '@tresjs/cientos'

const { texture } = useFBO({
  width: 512,
  height: 512
})