Cientos

Collection of useful helpers and fully functional, ready-made abstractions for Tres

• 💡 Build a 3D scene working only with Vue components.
• ⚡️ Powered by Vite
• 🥰 It brings all the updated features of ThreeJS right away regardless the version
• 🦾 Fully Typed

Cientos (the Spanish word for "hundreds", pronounced /θjentos/ ) is a collection of useful ready-to-go helpers and components that are not part of the core package. The name uses the word used in Spanish to multiply by 100, to refer to the potential reach of the package to hold an amazing abstraction.

The cientos package uses three-stdlib module under the hood instead of the three/examples/jsm module. This means that you don't need to extend the catalog of components using the extend method from the core, cientos does it for you.

It just works. 💯

Installation

pnpm i @tresjs/cientos

Docs

Checkout the docs

Demos

• Stackblitz Collection

Contributing

We are open to contributions, please read the contributing guide to get started.

Build

To build the package run:

pnpm run build

Playground

To run the playground run, is a great way to test the components and helpers locally:

First, install dependencies

pnpm i

And then to run the development server on http://localhost:5173

pnpm run playground

Test

TODO...

Docs

To run de docs in dev mode

pnpm run docs:dev

To build them

pnpm run docs:build

License

MIT

Sponsors

Be the first to support this project here ☺️.

Changelog

4.3.0 (2025-03-25)

Features

• environment: enhance environment and background props (#590) (7e96136)

4.2.0 (2025-03-07)

Features

• OrbitControls: add mouseButtons prop to customize mouse interactions (#603) (5a7c2ca)

4.1.1 (2025-03-05)

Bug Fixes

• remove will-change that makes Html components blurry (#602) (2b50296)
• update html on camera dolly zoom (#600) (e5628f2)

4.1.0 (2025-01-17)

Features

• Align: add component, demo, docs (#544) (e3ee52c)
• Billboard: add component, playground, docs (#527) (418e6ae)
• CubeCamera: add component, demo, docs (#537) (02ed01c)
• edges (#390) (60c200d)
• gradientTexture: add component, demo, docs (#531) (58d0fdb)
• Grid: add component, demo, docs (#540) (096ab5d)
• Image: add component, playground, docs (#529) (ad916a2)
• Mask: add component, demo, docs (#552) (0fb8952)
• MeshDiscardMaterial: add component, playground, docs (#525) (7a23019)
• Outline: add component, demo, docs (#532) (5bae4de)
• ScreenSizer: add component, playground, docs (#535) (ee5af96)
• ScreenSpace: add component, demo, docs (#536) (e43f112)
• SoftShadows: add component, demo, docs (#541) (e71cdad)

Bug Fixes

• 581 environment lightformers are not working (#584) (653a5df)
• build dts error TS7056 (#521) (c16c6e5)
• deps: update dependency @tresjs/core to v4.3.0 (#503) (83fa2bf)
• deps: update dependency vue-router to v4.4.5 (#488) (0840b88)
• instance properties and fix demo (#561) (f0fb337)
• KeyboardControls: support non-qwerty keyboards (#573) (#574) (efdde6d)
• MeshReflectionMaterial: remove unneeded material.onBeforeRender (#534) (f622324)
• typescript build issues (#578) (09584be)
• update core version with patch (#508) (cbae8ee)

4.0.3 (2024-10-04)

Bug Fixes

• deps: update dependency @tresjs/core to v4.2.10 (#479) (fb3026a)
• discrepancy between param enableDamping in OrbitControl (#486) (97a224c)

4.0.2 (2024-08-30)

Bug Fixes

• useGltf: use-loader fix for gltf with textures (#480) (f1f983f)

4.0.1 (2024-08-30)

Bug Fixes

• adapt to changes on useloader for Cube Textures (#476) (3641dc6)
• deps: update dependency @tresjs/core to v4.2.7 (#466) (0596353)

4.0.0 (2024-08-20)

Features

• Add cylinder component (9e17559)
• V4 (#420) (0cdd58e), closes #425 #439 #435 #441 #436 #428

Bug Fixes

• SkyDemo: value.value -> value (82fe77b)
• vue attrs hyphenation issues (4f9b61b)

4.0.0-rc.2 (2024-07-26)

4.0.0-rc.1 (2024-07-25)

Features

• fbo: add autoRender flag as an option to useFBO (#458) (ddcd4ac)

4.0.0-rc.0 (2024-07-24)

Features

• Sparkles: invalidate on update (#446) (cbfd226)

Bug Fixes

• reimplement ContactShadows for v4 (#449) (d71c328)
• update to core v4.2.2 to remove warning on invalidation (42afa6e)

4.0.0-next.1 (2024-07-17)

⚠ BREAKING CHANGES

• MeshReflectionMaterial: add features/docs, reorganize

Features

• 423 enable on demand render mode usage (#436) (b3eef40)
• AnimatedSprite: add asSprite prop (7a14b55)
• AnimatedSprite: dispose texture onUnmounted (18d6904)
• AnimatedSprite: remove explicit click event (042c350)
• AnimatedSprite: remove unnecessary Suspense (082d695)
• app: 421 Update components to use useLoop instead of useRenderLoop (ad3b290)
• app: Add the option for x and y in mouseparallax component (#444) (12d5834)
• re-remove tweakpane (#425) (72284ce)
• update to core v4.2 (14b30f9)

Bug Fixes

• Lensflare demo: add camera #435 (#441) (981de57)
• MeshReflectionMaterial: add features/docs, reorganize (58703e3)
• remove hardcoded speed number, that setting at 0 doesn't stop the effect (e67f3a2)
• SkyDemo: value.value -> value (82fe77b)
• types: fixed types generics for useGLTF (#448) (62a9bcc)
• uncomment section (fac2253)
• vue attrs hyphenation issues (4f9b61b)

4.0.0-next.0 (2024-03-27)

⚠ BREAKING CHANGES

• app: 349 Remove directives from cientos
• app: 227 Change the keyboardcontrols implementation

Features

• add arrow keys support (39e2094)
• AnimatedSprite: add AnimatedSprite, playground, docs (d6ea81b)
• AnimatedSprite: allow [numCols, numRows] as atlas prop (3309d9c)
• AnimatedSprite: always emit last frame name on loop and on end (ed16136)
• AnimatedSprite: change default fps (44831a4)
• app: 227 Change the keyboardcontrols implementation (fed0f86)
• app: 227 Final details, ready to go (6f06213)

Bug Fixes

• AnimatedSprite: return nullFrame animation if requested animation not found (453819e)
• Atlas: add missing argument to function call (e6b147e)

Code Refactoring

• app: 349 Remove directives from cientos (8fc4cd5)

3.9.0 (2024-05-07)

Features

• add local props (b9192fb)
• add camera recognition for default props setup (c8ebba0)
• app: 252 adding ocean component (7efb293)
• app: 252 Renamed as ocean, add sky support (473bac6)
• app: Add holographic material to cientos (f0f4eab)
• app: Add RoundedBox component (8b6cb67)
• cientos/positional-audio: add positional audio component (39c334c)
• cientos/positional-audio: adding more logic and examples for playground (73c94de)
• cientos/positional-audio: delete medias, modifications doc (ae34177)
• cientos/positional-audio: demo clean (7bc1b61)
• cientos/positional-audio: documentation v1, main example v1 (bb68bda)
• cientos/positional-audio: fix issues async, add gui example doc (65c4c17)
• cientos/positional-audio: fix lint issue, wip doc (4e2b5fb)
• cientos/positional-audio: fix material issue for the helper, documentation wip (e0d8f41)
• cientos/positional-audio: fix positional async helper and documentation (f1b9476)
• cientos/positional-audio: improve documentation (00c4551)
• cientos/positional-audio: improve documentation (eb30d85)
• cientos/positional-audio: improve documentation (8b65696)
• cientos/positional-audio: improve documentation (a0f02a2)
• cientos/positional-audio: improved code and documentation (46ca4c4)
• cientos/positional-audio: rename positionAudioRef (a036caa)
• cientos/positional-audio: start writing documentation (1824cbb)
• cientos/positional-audio: start writing documentation (6131e41)
• cientos/transform-controls: add camera prop (0ce732d)
• docs: add local prop to docs (d21694b)
• Fit: add component, playground, demo (a521903)

Bug Fixes

• add support for camera prop (7844743)
• app: 252 Apply review feedback (4449208)
• apply feedback (3a50bc2)
• camera controls ignored props (37fa163)
• docs: better description (703ab70)
• little detail in the interface (fb6456a)
• transformControls throws error when switching active camera (f1a477a)
• type: correct the east description (c26da1f)

4.0.0-next.0 (2024-03-27)

Features

• app: 252 adding ocean component (7efb293)
• app: 252 Renamed as ocean, add sky support (473bac6)
• app: Add RoundedBox component (8b6cb67)

Bug Fixes

• app: 252 Apply review feedback (4449208)
• apply feedback (3a50bc2)
• little detail in the interface (fb6456a)

3.8.0 (2024-02-07)

Features

• add BakeShadows component (77df084)
• add gltfExporter composable (0c77d33)
• app: 329 Add cast-shadow/receive-shadow to 3D model (471e28a)
• reflection material (5cccaa9)

Bug Fixes

• app: 336 Fix stats-gl problem (505e243)
• deps: update dependency @tresjs/core to v3.7.0 (#333) (4d09ebb)
• reduce beforeRenderer time (b9df580)
• reduce lagging on the reflection (dca5c31)

Reverts

• remove tweakpane (#313)" (#343) (1314abd)

3.7.0 (2023-12-13)

Features

• add 'change' event to pointerlock controls, improve docs (c394f10)
• add rectAreaLightHelper to vLightHelper directive (#283) (8bc64a1)
• add reflector (#136) (bd4d710)
• sampler and useSampler (#286) (826833c)

Bug Fixes

• remove wrapper element on unmounted (#310) (1a37c92)
• wrap Text3D inside Suspense in the docs (#307) (27ce1f0)

3.6.0 (2023-11-07)

Features

• cientos: Add CustomShaderMaterial wrapper (#261) (43701f8)
• Sparkles: add Sparkles (#253) (cbcc9b9)
• Superformula: add superformula (#274) (19130b4)

Bug Fixes

• avoid html container to be appended again (#278) (8c2b17d)

Reverts

• docs: remove docs/ from .gitignore (#272) (8b5577e)

3.5.1 (2023-10-18)

Bug Fixes

• add key to html slot wrapper to force re-render (#258) (f7a32e2)
• OrbitControls: expose ref (#250) (0f1d162)

3.5.0 (2023-10-10)

Features

• 178 v distance to (#220) (d2e2521)
• 23 html component (#184) (3a488f0)
• add <Fbo /> abstraction (#228) (6efc076)
• add global-audio component (f66d81d)
• change stats to renderless component (3ae6f5d)
• Lines: add CatumullRomLine, Line2 (4a267a5)
• Lines: add docs, correct name (f868d4e)
• Lines: adjust types (e876314)
• Lines: correct segments prop description (a22d25d)
• Lines: fix linter errors (6ab3ef5)
• Lines: format docs (a3b612f)
• Lines: format docs (28e78b1)
• Lines: make Line2 import relative (6788d8e)
• Lines: remove unneeded refs, objects from demos (128ea59)
• Lines: reword docs (45002ed)
• remove pauseTrigger, now play-trigger element also work for pause state when is playing (6973f23)

Bug Fixes

• 147 enhance environment and useenvironment abstractions (#219) (876fa9f)
• deps: update dependency @tresjs/core to v3.3.0 (#200) (c33d383)
• Levioso: changing speed causes jerkiness (#212) (a941576)
• v3.4.1 (#238) (8be6c82)

3.4.1 (2023-09-27)

Bug Fixes

• fake commit to force a patch (b1a055c)
• remove es only format bundle (b9bb1b9)

3.4.0 (2023-09-26)

Features

• add first directive vLog (071c63f)
• add smoke demo (6aa3f06)
• add stats-gl component (68bee97)
• add v-always-look-at directive (ab3cfa3)
• add v-light-helper component (d3e79d7)
• cientos: 176 remove models (#199) (1314488)
• cientos: 178 v-light-helper (#214) (0652eed)
• Lensflare: add color, distance, size, texture to component (f90988e)
• Lensflare: add defaultChoice (4246245)
• Lensflare: add docs (dcd956b)
• Lensflare: add Leches (14e03a0)
• Lensflare: add Lensflare (6605eaa)
• Lensflare: add Lensflare (fb1f52d)
• Lensflare: add seed, color (c895fe1)
• Lensflare: change exposed ref name (9279cfe)
• Lensflare: clean up imports (b8ef198)
• Lensflare: fix linter error (84f3a79)
• Lensflare: fix linter errors (224ecc4)
• Lensflare: fix path (7f18278)
• Lensflare: fix paths (7bc7cd2)
• Lensflare: formatting (fc8ad30)
• Lensflare: group constants into objects (022529f)
• Lensflare: guard against undefined ref value (2c6c912)
• Lensflare: move easing functions to /src/utils (f443bbc)
• Lensflare: move preset values to constants.ts (9766d6b)
• Lensflare: move to own subdirectory (76e897c)
• Lensflare: refactor Leches setup (f8c69c0)
• Lensflare: refactor Leches setup (0715ccf)
• Lensflare: remove 4, 8 sided textures (3c23042)
• Lensflare: remove duplicate RandUtils (d816e8e)
• Lensflare: remove scaleRef from demo (50271ea)
• Lensflare: rename folder (3fc7374)
• Lensflare: rename function, variables (e0c382d)
• Lensflare: rename prop flare -> elements (fb199f6)
• Lensflare: resolve infinite while loop bug (dfa5d8a)
• Lensflare: scale fix (c439895)
• Lensflare: simplify prop precedence (91833e6)
• Lensflare: smooth out types/conversion (b9a60e8)
• Lensflare: update route to LensflareDemo (7dfce1b)
• Lensflare: update seed with random value (fba64dc)
• Lensflare: use Tresjs/assets for texture URLS (3dc7e90)
• RandUtils: add RandUtils (e1693c1)
• RandUtils: add RandUtils (5fa7111)
• remove cardbobot, suzanne. Add blender-cube in backdrop demo (c9f95ac)
• Sky: add distance prop to docs (5c29e9b)
• Sky: add distance to demo (7440216)
• Sky: add docs (110e4a8)
• Sky: add exposure to demo (323fc82)
• Sky: add Sky (894d71e)
• Sky: change azimuth default (12b7c38)
• Sky: disable zoom/pan idiomatically in demo (08d2f67)
• Sky: fix linter whitespace errors (dbc191d)
• Sky: make prop descriptions consistent in docs (a62b6d2)
• Sky: remove grid (0eaa3e6)
• Sky: remove unused ref from from demo (4968785)
• Sky: set demo max mieDirectionalG to 0.99 (a4475db)
• Sky: use Vue props instead of watchers for uniforms (c45ed6f)

Bug Fixes

• check background prop if its empty string (#217) (ec20d69)
• use camera's z position as default distance in CameraControls (8a62a43)

3.3.0 (2023-09-11)

Features

• 158 stats (#166) (4a71885)
• add distance prop in camera controls (388b5de)
• SVG (28e3b6a)
• SVG: add depth demo (ba1fd18)
• SVG: add depth options (e453a1d)
• SVG: add docs (b176dc4)
• SVG: change 'depth' default to 'renderOrder' (5c1dd27)
• SVG: dispose of geometries (a75d571)
• SVG: fix linter warnings (80dbaab)
• SVG: fix type error (4439aa1)
• SVG: remove depth prop demo (ca82737)
• SVG: remove depth prop from demo (87ceb34)
• SVG: remove key (01061a9)
• SVG: remove unused variable (c85a96f)
• SVG: rename exposed ref (95bada9)
• SVG: split line for linter (469273a)
• SVG: update JSDoc (8c0aaf6)
• SVG: update props, depth in docs (da85374)
• SVG: whitespace (d83493b)
• update lint rules, (#196) (ccdf81f)

Bug Fixes

• cientos: controls props priority (a9e47fc)
• dead link (f784021)
• set @tresjs/core as peer (#211) (9636ec9)

3.3.0-next.0 (2023-09-11)

Features

• 158 stats (#166) (4a71885)
• add distance prop in camera controls (388b5de)
• SVG (28e3b6a)
• SVG: add depth demo (ba1fd18)
• SVG: add depth options (e453a1d)
• SVG: add docs (b176dc4)
• SVG: change 'depth' default to 'renderOrder' (5c1dd27)
• SVG: dispose of geometries (a75d571)
• SVG: fix linter warnings (80dbaab)
• SVG: fix type error (4439aa1)
• SVG: remove depth prop demo (ca82737)
• SVG: remove depth prop from demo (87ceb34)
• SVG: remove key (01061a9)
• SVG: remove unused variable (c85a96f)
• SVG: rename exposed ref (95bada9)
• SVG: split line for linter (469273a)
• SVG: update JSDoc (8c0aaf6)
• SVG: update props, depth in docs (da85374)
• SVG: whitespace (d83493b)
• update lint rules, (#196) (ccdf81f)

Bug Fixes

• cientos: controls props priority (a9e47fc)
• dead link (f784021)
• set @tresjs/core as peer (77f7a3c)

3.2.1 (2023-09-01)

Bug Fixes

• deps: update dependency @tresjs/core to v3.1.1 (#186) (0f5d9cf)
• removed toFixed for progress value (#191) (d46f90f)

3.2.0 (2023-08-25)

Features

• 107 use video texture (#167) (f0f1f9b)
• add glass material (#172) (5f60864)

Bug Fixes

• 179 tweakpane plugin essentials (#180) (67b8d57)

3.2.0-next.0 (2023-08-23)

Features

• 107 use video texture (#167) (f0f1f9b)

Bug Fixes

• remove tweakpane essentials import (eeed334)

3.1.0 (2023-08-17)

Features

• add camera controls to new context (21ab955)
• chg to event, rmv vmodel, (9b739a2)
• remove tweakpane deps from final bundle (#169) (b99ac3c)

Bug Fixes

• useGLTF return types (#174) (7f78106)

3.0.1 (2023-07-29)

Bug Fixes

• removed axesHelper from Contact Shadows (#152) (821205a)

3.0.0 (2023-07-29)

⚠ BREAKING CHANGES

• core v3 provides a new state context useTresContext which impacts all the abstractions depending on the state

• chore: move core to deps

• chore: updated lock

• chore: fix lint

• feat: removed useCientos and useTresContext instead

Features

• 120 refactor usecientos to new state context provider (#143) (723a323)
• add more camera-controls playground examples (d3c5dd3)
• add preliminary camera-controls abstraction (bef41b9)
• backdrop stage abstraction (#116) (62f677c)

Bug Fixes

• add reactivity to stars component, rmv factor as props unnecessary (#144) (ad5c6c8)
• background not checked right useEnvironment (#138) (28d40fd)
• map correct camera-controls events (e7095eb)
• MouseParallax, clean code (#134) (257238a)
• nuxt problem with scrollControls (#130) (1739965)

2.3.0 (2023-07-11)

Features

• scroll-controls (#118) (293fcdc)

Bug Fixes

• initial camera position in keyboard controls (#119) (e4a03a6)
• remove deconstructive props (#124) (d83d00d)

2.2.0 (2023-06-29)

Features

• keyboard controls (#68) (1b7a624)
• useProgress composable (b6f3f33)

Bug Fixes

• add playground to examples (#104) (ce442a4)
• added default for touches prop (#100) (#111) (de6ebab)
• deps: update dependency @tresjs/core to v2.3.0 (599f36b)
• styles in dark theme, same as in the core (#105) (1a8d0a5)
• useProgress correct export from loaders (af33533)

2.1.4 (2023-06-14)

Bug Fixes

• chg log linter rule to warn (18eeb72)
• fix types in precipitation, stars. rmv log rule linter (1c15ecb)
• precipitation-area issue, rmv log mouseparallax, add rule lint (994efaa)
• return control value on event emitters (d072223)

2.1.2 (2023-05-26)

Bug Fixes

• fix lint on the demo (8873e41)
• refactor transform controls with deconstructor (8e7f673)

2.1.1 (2023-05-24)

Bug Fixes

• contact shadows helper as prop (f7054d0)

2.1.0 (2023-05-24)

Features

• add events to orbit controls (6815d12)
• add Rain component (7dca86d)
• contact shadows is alive and reactive (188cf8c)
• contact-shadows implementation (81baf86)
• deconstruct those Props (ccd0581)
• enhanced orbit-controls (27f2e88)
• temporally tweak eslint for deconstructed props (8803e8f)
• update parallax mouse abstraction (88885a3)
• update to core v2.1.0 and fix types (f099387)

Bug Fixes

• added missing prop target and removed withDefaults (43ddf6b)
• change smoke texture encoding for colorSpace (2338803)
• core types (266088b)
• event headline h2 (c506769)
• remove import leftovers (fef7e86)
• templateRef name casing (8844612)

2.0.0 (2023-05-12)

2.0.0-rc.3 (2023-05-08)

Bug Fixes

• fbxModel inherit props (b15935e)
• gltfModel inherit props (a80506e)

2.0.0-rc.1 (2023-05-03)