Cursor pos snippets (#540)

* cursor pos in the UI

* raycast snippet

Author: nearnshaw

content/creator/sdk7/interactivity/raycasting.md

@@ -194,11 +194,18 @@ raycastSystem.registerLocalDirectionRaycast(
 ```
 
 {{< hint warning >}}
-**📔 Note**: You can get a raycast result from hitting an entity on a different scene. This may be especially useful when creating portable experiences or smart wearables, that can react to the surroundings.
-
-However, note that currently you can only obtain raycast responses when the collision is with conent in a scene done with SDK7. Older SDK6 scenes won't return any hit result.
+**📔 Note**: You can get a raycast result from hitting an entity on a different scene.
 {{< /hint >}}
 
+## Handle hit entities
+ 
+When you get a raycast result that hit an entity, you can use the `entityId` to interact with the entity and its components. An entity is  [nothing more than a number]({{< ref "/content/creator/sdk7/architecture/entities-components.md#overview" >}}), so the `entityId` value itself can be interpreted as an `Entity` type.
+
+```ts
+const hitEntity = result.entityId as Entity
+const transform = Transform.get(entity)
+console.log(transform.position)
+```
 
 ## Collision layers
 
@@ -384,6 +391,74 @@ raycastSystem.registerGlobalDirectionRaycast(
 **📔 Note**: Keep in mind that in 3rd person the cursor could in the future not behave the same as in 1st person. It's recommended to only use this if the player is in 1st person.
 {{< /hint >}}
 
+## Raycast from the cursor position
+
+You can also trace a ray from the player's cursor position into the 3D world. This can be used to drag objects around, shooters, etc.
+
+```ts
+import { engine, Entity, InputAction, inputSystem, PointerEventType, RaycastQueryType, raycastSystem, TextShape, Transform } from '@dcl/sdk/ecs'
+import { EntityNames } from '../assets/scene/entity-names'
+import { PrimaryPointerInfo } from '@dcl/sdk/ecs'
+
+let cooldown = 1
+let rayFrequency = 0.1
+let mousePressed = false
+
+export function main() {
+   engine.addSystem(rayCastSystem)
+}
+
+const rayCastSystem = (t: number) => {
+
+    if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)) {
+      mousePressed = true
+    }
+
+    if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_UP)) {
+      mousePressed = false
+    }
+
+    if (!mousePressed) {
+      cooldown = 0
+      raycastSystem.removeRaycasterEntity(engine.CameraEntity)
+      return
+    }
+
+    cooldown += t
+    if (cooldown > rayFrequency) return
+    cooldown = 0
+
+    const pointerInfo = PrimaryPointerInfo.getOrCreateMutable(engine.RootEntity)
+    let dir = pointerInfo.worldRayDirection
+
+    raycastSystem.registerGlobalDirectionRaycast(
+      {
+        entity: engine.CameraEntity,
+        opts: {
+          queryType: RaycastQueryType.RQT_HIT_FIRST,
+          direction: dir,
+        },
+      },
+      function (raycastResult) {
+        let result = raycastResult.hits[0]
+
+        // do something in the hit position
+        if (result && result.position) {
+          console.log("x:", result.position.x, ", y:", result.position.y, ", z:", result.position.z)
+        }
+
+        // do something with the hit entity
+        const entity = result.entityId as Entity
+        if (entity) {
+          console.log("entity: ", entity)
+        }
+      }
+    )
+}
+
+```
+
+
 ## Advanced syntax
 
 ### Create a raycast component

content/creator/sdk7/interactivity/user-data.md

@@ -435,17 +435,62 @@ The `primaryPointerInfo` component returns an object with the following properti
 - `pointerType`: 0 for `none`, 1 for `mouse`
 
 
-You can use the `worldRayDirection` to set the `direction` field of a raycast to know if an entity is in the cursor's line of sight. See [Raycasting]({{< ref "/content/creator/sdk7/interactivity/raycasting.md" >}}) for more details.
-
-
 {{< hint info >}}
 **💡 Tip**: To react to simple hover events on UI elements, you may find it easier to use the `onMouseEnter` and `onMouseLeave` events, see [UI Button Events]({{< ref "/content/creator/sdk7/2d-ui/ui_button_events.md#hover-feedback" >}}). 
 {{< /hint >}}
 
 
+The `primaryPointerInfo` component is read-only, you can't force the player to change the cursor position.
 
 
-The `primaryPointerInfo` component is read-only, you can't force the player to change the cursor position.
+The following example shows how to display the cursor position on a UI element.
+
+
+_**ui.tsx file:**_
+```tsx
+import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
+import { Color4 } from '@dcl/sdk/math'
+import {cursorXpos, cursorYpos} from './index'
+
+export const uiMenu = () => (
+  <UiEntity
+    uiTransform={{
+			width: '100%',
+			height: '100px',
+			justifyContent: 'center',
+			alignItems: 'center',
+    }}
+    uiText={{ value: `Cursor pos: `+  cursorXpos + `,` + cursorYpos, fontSize: 40 }}
+    uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
+  />
+)
+```
+
+_**index.ts file:**_
+```ts
+import { engine } from '@dcl/sdk/ecs'
+import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+import { uiMenu } from './ui'
+
+export function main() {
+  ReactEcsRenderer.setUiRenderer(uiMenu)
+}
+
+export let cursorXpos: number | undefined = undefined
+export let cursorYpos: number | undefined = undefined
+
+function CursorSystem() {
+  const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
+  console.log(pointerInfo)
+
+  cursorXpos = pointerInfo.screenCoordinates?.x
+  cursorYpos = pointerInfo.screenCoordinates?.y
+}
+
+engine.addSystem(CursorSystem)
+```
+
+You can use the `worldRayDirection` to set the `direction` field of a raycast to know if an entity is in the cursor's line of sight. See [Raycasting]({{< ref "/content/creator/sdk7/interactivity/raycasting.md" >}}) for more details.