{"id":21176841,"url":"https://github.com/c-frame/aframe-cursor-teleport","last_synced_at":"2025-04-09T10:10:15.390Z","repository":{"id":39040193,"uuid":"283040534","full_name":"c-frame/aframe-cursor-teleport","owner":"c-frame","description":"An A-Frame component for navigating scenes on non-VR devices","archived":false,"fork":false,"pushed_at":"2025-02-21T10:43:32.000Z","size":13575,"stargazers_count":34,"open_issues_count":7,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T03:54:49.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c-frame.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"vincentfretin","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2020-07-27T23:21:40.000Z","updated_at":"2025-02-21T10:43:22.000Z","dependencies_parsed_at":"2023-02-13T15:31:24.626Z","dependency_job_id":"d0c68fdd-15eb-40c7-8449-27b4dae1542d","html_url":"https://github.com/c-frame/aframe-cursor-teleport","commit_stats":{"total_commits":70,"total_committers":5,"mean_commits":14.0,"dds":"0.27142857142857146","last_synced_commit":"e5b12d842c10caecaa8f65ac87279d052ba9e651"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-frame%2Faframe-cursor-teleport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-frame%2Faframe-cursor-teleport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-frame%2Faframe-cursor-teleport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-frame%2Faframe-cursor-teleport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c-frame","download_url":"https://codeload.github.com/c-frame/aframe-cursor-teleport/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018061,"owners_count":21034048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T17:12:24.205Z","updated_at":"2025-04-09T10:10:15.298Z","avatar_url":"https://github.com/c-frame.png","language":"JavaScript","funding_links":["https://github.com/sponsors/vincentfretin"],"categories":[],"sub_categories":[],"readme":"## aframe-cursor-teleport-component\n\n[![Version](http://img.shields.io/npm/v/aframe-cursor-teleport-component.svg?style=flat-square)](https://npmjs.org/package/aframe-cursor-teleport-component)\n[![License](http://img.shields.io/npm/l/aframe-cursor-teleport-component.svg?style=flat-square)](https://npmjs.org/package/aframe-cursor-teleport-component)\n\n![Screenshot](https://github.com/c-frame/aframe-cursor-teleport/raw/master/capture-01.gif)\n\nA simple A-Frame component for navigating scenes on non-VR devices. When combined with A-Frame's cursor and look-controls components, this allows users to freely explore A-Frame scenes using device orientation and touch on mobile or using the mouse on desktop.\n\n- [Live Example - Basic](https://c-frame.github.io/aframe-cursor-teleport/examples/basic/index.html)\n- [Live Example - Custom Collision](https://c-frame.github.io/aframe-cursor-teleport/examples/custom/index.html)\n\nFor [A-Frame](https://aframe.io).\n\n### API\n\n| Property          | Description                                                                                                      | Default Value |\n| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------- |\n| enabled           | Enable or disable the component                                                                                  | true          |\n| cameraRig         | Selector of the camera rig to teleport                                                                           |               |\n| cameraHead        | Selector of the scene's active camera                                                                            |               |\n| cursorColor       | Color of the cursor, default blue                                                                                | '#4d93fd'     |\n| cursorType        | Type of the cursor, cylinder or ring                                                                             | 'cylinder'    |\n| collisionEntities | Selector of the meshes used to check the collisions. If no value provided a plane at Y=0 is used.                |               |\n| defaultPlaneSize  | Size of the default plane created for collision when `collisionEntities` is not specified                        | 100           |\n| ignoreEntities    | Selector of meshes that may obstruct the teleport raycaster, like UI or other clickable elements.                |               |\n| landingNormal     | Normal vector to detect collisions with the `collisionEntities`                                                  | (0, 1, 0)     |\n| landingMaxAngle   | Angle threshold (in degrees) used together with `landingNormal` to detect if the mesh is so steep to jump to it. | 45            |\n\n### Events\n\nThe `cursor-teleport` component will emit two events:\n\n- `navigation-start`: Entity beginning travel to a destination.\n- `navigation-end`: Entity has reached destination.\n\n### Installation\n\n#### Browser\n\nInstall and use by directly including the [browser files](dist):\n\n```html\n\u003chead\u003e\n  \u003ctitle\u003eMy A-Frame Scene\u003c/title\u003e\n  \u003cscript src=\"https://aframe.io/releases/1.7.0/aframe.min.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"https://cdn.jsdelivr.net/gh/c-frame/aframe-cursor-teleport@1.6.0/dist/aframe-cursor-teleport-component.min.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003ca-scene\u003e\n    \u003c!-- see usage below --\u003e\n  \u003c/a-scene\u003e\n\u003c/body\u003e\n```\n\n#### npm\n\nInstall via npm:\n\n```bash\nnpm install aframe-cursor-teleport-component\n```\n\nThen require and use.\n\n```js\nrequire('aframe');\nrequire('aframe-cursor-teleport-component');\n```\n\n### Usage\n\n#### Basic Setup\n\n```html\n\u003ca-scene cursor=\"rayOrigin: mouse\"\u003e\n  \u003ca-entity id=\"cameraRig\" cursor-teleport=\"cameraRig: #cameraRig; cameraHead: #head\"\u003e\n    \u003ca-entity id=\"head\" position=\"0 1.6 0\" camera look-controls=\"reverseMouseDrag: true\"\u003e\u003c/a-entity\u003e\n  \u003c/a-entity\u003e\n\u003c/a-scene\u003e\n```\n\n#### Collision Entities\n\nTo add collision objects, simply identify them with a selector:\n\n```html\n\u003ca-scene cursor=\"rayOrigin: mouse\"\u003e\n  \u003c!-- camera rig --\u003e\n  \u003ca-entity id=\"cameraRig\" cursor-teleport=\"cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision\"\u003e\n    \u003ca-entity id=\"head\" position=\"0 1.6 0\" camera look-controls=\"reverseMouseDrag: true\"\u003e\u003c/a-entity\u003e\n  \u003c/a-entity\u003e\n\n  \u003c!-- collidable entity --\u003e\n  \u003ca-entity\n    class=\"collision\"\n    position=\"0 -0.05 0\"\n    geometry=\"primitive: box; width: 8; height: 0.1; depth: 8\"\n  \u003e\u003c/a-entity\u003e\n\u003c/a-scene\u003e\n```\n\n#### Ignored Entities\n\nIf your scene has interactive entities that should not initiate a teleport when clicked, you can add them to the ignoredEntities array using a selector:\n\n```html\n\u003ca-scene cursor=\"rayOrigin: mouse\" raycaster=\"objects: .clickable\"\u003e\n  \u003c!-- camera rig --\u003e\n  \u003ca-entity\n    id=\"cameraRig\"\n    cursor-teleport=\"cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable\"\n  \u003e\n    \u003ca-entity id=\"head\" position=\"0 1.6 0\" camera look-controls=\"reverseMouseDrag: true\"\u003e\u003c/a-entity\u003e\n  \u003c/a-entity\u003e\n\n  \u003c!-- collidable entity --\u003e\n  \u003ca-entity\n    class=\"collision\"\n    position=\"0 -0.05 0\"\n    geometry=\"primitive: box; width: 8; height: 0.1; depth: 8\"\n  \u003e\u003c/a-entity\u003e\n\n  \u003c!-- UI element --\u003e\n  \u003ca-entity\n    class=\"clickable\"\n    color-change\n    geometry=\"primitive: octahedron\"\n    scale=\"0.2 0.2 0.2\"\n    position=\"-0.8 1 -1.5\"\n  \u003e\u003c/a-entity\u003e\n\u003c/a-scene\u003e\n```\n\n#### Use with aframe-blink-controls\n\nThis component works with [aframe-blink-controls](https://github.com/jure/aframe-blink-controls) allowing for easy-to-use navigation across virtually all devices:\n\n```html\n\u003ca-scene cursor=\"rayOrigin: mouse\" raycaster=\"objects: .clickable\"\u003e\n  \u003c!-- camera rig --\u003e\n  \u003ca-entity\n    id=\"cameraRig\"\n    cursor-teleport=\"cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable\"\n  \u003e\n    \u003ca-entity id=\"head\" position=\"0 1.6 0\" camera look-controls=\"reverseMouseDrag: true\"\u003e\u003c/a-entity\u003e\n    \u003ca-entity\n      laser-controls=\"hand: left\"\n      raycaster=\"objects: .clickable; far: 100\"\n      line=\"color: red; opacity: 0.75\"\n      blink-controls=\"cameraRig: #cameraRig; teleportOrigin: #head;\"\n    \u003e\u003c/a-entity\u003e\n    \u003ca-entity\n      laser-controls=\"hand: right\"\n      raycaster=\"objects: .clickable\"\n      line=\"color: red; opacity: 0.75\"\n      blink-controls=\"cameraRig: #cameraRig; teleportOrigin: #head;\"\n    \u003e\u003c/a-entity\u003e\n  \u003c/a-entity\u003e\n\n  \u003c!-- collidable entity --\u003e\n  \u003ca-entity\n    class=\"collision\"\n    position=\"0 -0.05 0\"\n    geometry=\"primitive: box; width: 8; height: 0.1; depth: 8\"\n  \u003e\u003c/a-entity\u003e\n\n  \u003c!-- UI element --\u003e\n  \u003ca-entity\n    class=\"clickable\"\n    color-change\n    geometry=\"primitive: octahedron\"\n    scale=\"0.2 0.2 0.2\"\n    position=\"-0.8 1 -1.5\"\n  \u003e\u003c/a-entity\u003e\n\u003c/a-scene\u003e\n```\n\n#### Use with simple-navmesh-constraint\n\nYou should disable the `simple-navmesh-constraint` component during the navigation transition.\nYou can do that like this:\n\n```html\n\u003cscript\u003e\n  AFRAME.registerComponent('character-controller', {\n    events: {\n      'navigation-start': function () {\n        if (this.el.hasAttribute('simple-navmesh-constraint')) {\n          this.el.setAttribute('simple-navmesh-constraint', 'enabled', false);\n        }\n      },\n      'navigation-end': function () {\n        if (this.el.hasAttribute('simple-navmesh-constraint')) {\n          this.el.setAttribute('simple-navmesh-constraint', 'enabled', true);\n        }\n      }\n    }\n  });\n\u003c/script\u003e\n```\n\nThen add `character-controller` component to your cameraRig entity. You also probably want to add `.navmesh-hole` to the `cursor-teleport`'s `ignoreEntities`:\n\n```html\n\u003ca-entity\n  id=\"cameraRig\"\n  character-controller\n  cursor-teleport=\"cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable,.navmesh-hole\"\n\u003e\n  \u003ca-entity id=\"head\" position=\"0 1.6 0\" camera look-controls=\"reverseMouseDrag: true\"\u003e\u003c/a-entity\u003e\n\u003c/a-entity\u003e\n```\n\n#### teleportTo API\n\nYou can use the same teleport animation programmatically to teleport to a destination knowing\nthe position and quaternion (optional):\n\n```js\nconst cameraRig = document.getElementById('cameraRig');\nconst cursorTeleport = cameraRig.components['cursor-teleport'];\ncursorTeleport.teleportTo(destination.object3D.position, destination.object3D.quaternion);\n```\n\nLook at the source code of the basic example, the black button triggers the teleportation to the black arrow on the second platform.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc-frame%2Faframe-cursor-teleport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc-frame%2Faframe-cursor-teleport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc-frame%2Faframe-cursor-teleport/lists"}