Merge branch 'main' into offset-and-tiling

content/creator/deprecated/scenes/projects/scene-metadata.md

@@ -277,7 +277,7 @@ There is a third category for scenes: 🔴 `R` for Restricted. This rating is ma
 Scenes with this rating won't load and no one will be able to interact with them. If your scene falls into this category, you should review and update it to comply with the [Content Policy](https://decentraland.org/content).
 
 {{< hint warning >}}
-**📔 Note**: Incorrectly categorizing your scene may result in player reports and subsequent moderation actions. For more details, refer to [Age Rating and Scene Reporting]({{< ref "/content/player/general/in-world-features/age-rating.md" >}}).
+**📔 Note**: Incorrectly categorizing your scene may result in player reports and subsequent moderation actions. For more details, refer to [Age Rating and Scene Reporting]({{< ref "/content/player/exploring/age-rating.md" >}}).
 {{< /hint >}}
 
 ## Required Permissions

content/creator/scene-editor/smart-items/combine-with-code.md

@@ -15,18 +15,26 @@ The Creator Hub plus custom code is a very powerful combination for creating con
 
 For example, you can take advantage of an existing lever smart item, that already comes with its sounds and animations and states, and write code that detects when the lever is pulled to run your own custom logic.
 
-Click the **< > CODE** button to open Visual Studio Code on your scene project.
+{{< hint warning >}}
+**📔 Note**: Install [Visual Studio Code](https://code.visualstudio.com/), if you don't have it already.
+{{< /hint >}}
+
+## Open a scene's code
+
+Once you installed VS Studio Code on your machine, you can click the **< > CODE** button to open Visual Studio Code on your scene project.
 
 <img src="/images/editor/code-button.png" width="200"/>
 
 This opens a separate window with Visual Studio Code. On the left margin you can navigate the files and folder structure of your project.
 
 <img src="/images/editor/files-on-vs-studio.png" alt="Scene name" width="200"/>
 
-{{< youtube J_EO1LZkaiA >}}
+Add your custom code in the `index.ts` file under `/src`, inside the `main()` function. You can otherwise add custom code outside that function or create new `.ts` files inside the `/src` folder, but these must be somehow referenced inside the `main()` function of `index.ts`.
+
+If you have a preview window open running your scene, whenever you change the code in your files and save, the scene reloads automatically with your changes.
 
 {{< hint warning >}}
-**📔 Note**: Install [Visual Studio Code](https://code.visualstudio.com/), if you don't have it already.
+**📔 Note**: If you have VS Code installed but the **CODE** button doesn't open it, it may be that VS Code is not properly configured on your machine to open via the command line. In most cases, this is care of as part of the default installation, but in case it's not, see [these instructions from VS](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) to enable VS Code from the command line.
 {{< /hint >}}
 
 ## Reference an item
@@ -88,6 +96,7 @@ For example, if a scene has a button with the following generic **On Click** eve
 <img src="/images/editor/restart-button.png" width="600" />
 
 ```ts
+import { engine } from '@dcl/sdk/ecs'
 import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events'
 import { TriggerType } from '@dcl/asset-packs'
 
@@ -110,6 +119,7 @@ You can also use custom code to activate trigger events based on your own custom
 <img src="/images/editor/door-triggers.png" width="600" />
 
 ```ts
+import { engine } from '@dcl/sdk/ecs'
 import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events'
 import { TriggerType } from '@dcl/asset-packs'
 
@@ -133,6 +143,7 @@ For example, if a scene has a door with the following default **Open** action, y
 <img src="/images/editor/door-actions.png" width="600" />
 
 ```ts
+import { engine } from '@dcl/sdk/ecs'
 import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events'
 import { TriggerType } from '@dcl/asset-packs'
 
@@ -159,6 +170,7 @@ function main() {
 You can also emit action events from your code, this allows you to take advantage of actions that are already defined inside the smart item's Action component. The following snippet calls the "Open" action on a door smart item whenever a button smart item is triggered.
 
 ```ts
+import { engine } from '@dcl/sdk/ecs'
 import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events'
 import { TriggerType } from '@dcl/asset-packs'
 

content/creator/scene-editor/smart-items/custom-items.md

@@ -0,0 +1,72 @@
+---
+date: 2025-01-02
+title: Custom Items
+description: Create your own custom items to reuse on any of your scenes.
+categories:
+  - scene-editor
+type: Document
+url: /creator/editor/custom-items
+weight: 8
+---
+
+Define a Custom Item to reuse it easily on any of your scenes, or share it with other scene creators. Custom items can consist of a single entity, or as many entities as you want. Custom items can be variations of existing Smart Items, or entirely custom, with their own tailored models and functionality.
+
+{{< youtube 7cGLu8P7dso >}}
+
+
+## How to Define a Custom Item
+
+Right-click on an entity on the [Entity Tree]({{< ref "/content/creator/scene-editor/scene-editor-essentials.md#the-entity-tree" >}}), or select several entities and then right-click on them. Select **Create Custom Item**.
+
+<img src="/images/editor/create-custom-item.png" width="300"/>
+
+On the lower section of the screen you are then asked to give your new Custom Item a name.
+
+<img src="/images/editor/name-custom-item.png" width="300"/>
+
+The item is now listed on the **Custom Items** tab, at the bottom of your screen. This tab is only displayed if at least one Custom Item exists in your workspace.
+
+<img src="/images/editor/custom-items.png" width="300"/>
+
+When defining a custom item, you can select several entities at a same hierarchical level, but not entities from separate parents if they don't share a common ancestor. Any nested entities are automatically included as part of the custom item, they don't need to be selected.
+
+The original entities in your scene aren't affected by the action of defining a Custom Item.
+
+{{< hint warning >}}
+**📔 Note**:
+When defining a Custom Item, you take a snapshot of the state of every component on the selected entities (except for the root entity's position, rotation, and scale). This includes **Actions**, **Triggers**, **Multiplayer**, **Visibility**, and any other component.
+
+Any smart item actions and triggers will self-reference their own copy. For example, if you define a Custom Item that includes an elevator and buttons, the buttons on each copy of the elevator will control the copy of the elevator that they belong to, not the original copy of the elevator.
+{{< /hint >}}
+
+## Using Custom Items
+
+Simply drag the item from the **Custom Items** tab into your scene.
+
+Once added, you're free to alter any property of a Custom Item, the changes you make only affect _that copy_ of the Custom Item. You can also edit or delete the original items that the Custom Item was defined from, this won't affect existing or future copies.
+
+Notice that Custom Items are displayed with a different icon on the Entity Tree. At the top of the Item properties menu on the right, you'll also see a mention of which Custom Item they were created from.
+
+To delete a custom item, right-click on the item on the **Custom Items** menu and select **Delete**. This action doesn't affect any existing copies of the item on your scenes, orphaned Custom Items remain on your scene unchanged. Deleting a Custom Item definition only removes it from the Custom Items tab.
+
+To rename a Custom Item, right click on the Custom Item definition on the **Custom Items** tab and select **Rename**.
+
+You can't modify the definition of a Custom Item that's already created, you must create a new definition and delete the original.
+
+## Sharing Custom Items
+
+You can share your custom items with other creators, so they can use them on their own scenes.
+
+Custom Items are stored each on a separate folder on your local machine
+
+- In Windows: _User/AppData/Roaming/creator-hub/Custom Items_
+- In Mac: _Users/username/Library/Application Support/creator-hub/Custom Items_
+
+{{< hint warning >}}
+**📔 Note**:
+The _Library_ folder is hidden in Mac by default. The easiest way to access it is by opening Go > Go to Folder, and Typing _/Library_
+{{< /hint >}}
+
+To share with someone else, simply navigate with your file explorer of choice and copy the full folder for the item. The person using your Custom Item must then paste it on their own Custom Item path on their machine. This folder contains everything needed to use your Custom Item. If they can't see it in their **Custom Items** tab, users may need to close and re-open the project.
+
+Any **Assets** used by your Custom Item are also stored in the Custom Item's folder. This includes any 3D models, images, sounds, and videos referenced by the item.

content/creator/scene-editor/smart-items/play-videos.md

@@ -31,7 +31,11 @@ You can configure the volume of the video's sounds. Note that the audio from the
 You can also configure the video to either loop or play once.
 
 {{< hint warning >}}
-**📔 Note**: Avoid playing more than one video at any given time in your scene, because it can severely impact performance for players. Always stop other videos before playing a second video.
+**📔 Note**: If too many videos are playing at the same time in your scene, some will be paused by the engine. The priority is determined based on proximity to the player, direction of the camera and size of the screen. The maximum amount of simultaneous videos depends on the player's quality settings.
+
+- Low: 1
+- Medium: 5
+- High: 10
 
 We also recommend starting to play the video when the player is near or performs an action to do that. Starting to play a video when your scene is loaded far in the horizon will unnecessarily affect performance while players visit neighboring scenes.
 {{< /hint >}}

content/creator/sdk7/2d-ui/ui-positioning.md

@@ -199,9 +199,11 @@ examples:
 ```ts
 ``` -->
 
-## UI Canvas Information
+## Responsive UI size
 
-Instead of positioning and scaling UI elements in terms of screen percentages, you can also obtain the canvas dimensions and then calculate the absolute positions following your own custom logic. For example, you could chose different dialog arrangements depending on the screen size.
+Players with different screen sizes may see your UI layout differently. If you set the size of any UI element to a fixed number of pixels, this UI may look too small to read on retina displays, that have a much higher pixel density.
+
+Instead of positioning and scaling UI elements in terms of screen percentages, you can also obtain the canvas dimensions and then calculate the absolute positions and sizes following your own custom logic. For example, you could chose different dialog arrangements depending on the screen size.
 
 To obtain information about the screen's dimension, you can check the `UiCanvasInformation`, that's added by default to the scenes's root entity.
 
@@ -222,3 +224,72 @@ export function Main(){
 	console.log("CANVAS DIMENSIONS: ", canvas.width, canvas.height)
 })
 ```
+
+The following snippet continually calculates a multiplier value based on the screen size:
+
+```ts
+import { engine, UiCanvasInformation } from "@dcl/sdk/ecs"
+
+let timer = 0
+let canvasInfoTimer = 0.5
+export let scaleFactor = 1
+
+export function UIScaleUpdate() {
+
+  engine.addSystem((dt) => {
+    timer += dt
+
+    if (timer <= canvasInfoTimer) return
+    timer = 0
+
+    const uiCanvasInfo = UiCanvasInformation.getOrNull(engine.RootEntity)
+
+    if (!uiCanvasInfo) return
+
+    const newScaleFactor = Math.min(uiCanvasInfo.width / 1920, uiCanvasInfo.height / 1080)
+
+    if (newScaleFactor !== scaleFactor) {
+      scaleFactor = newScaleFactor
+      console.log('NEW UI scaleFactor: ', scaleFactor)
+    }
+  })
+}
+```
+
+The value of the `scaleFactor` variable, that this function updates, can then be used as a multiplier on any UI element in the scene, including `heigh`, `width` and `fontSize` values.
+
+```ts
+import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+import { scaleFactor } from './calculate-scale-factor'
+
+ReactEcsRenderer.setUiRenderer(() => (
+	<UiEntity
+		uiTransform={{
+			width: 200 * scaleFactor,
+			height: 100 * scaleFactor,
+			justifyContent: 'center',
+			alignItems: 'center',
+			padding: 4 * scaleFactor
+		}}
+		uiBackground={{ color: Color4.Green() }}
+	>
+	  	<Label
+		        value={description}
+		        fontSize={18 * scaleFactor}
+		        textAlign="middle-center"
+		        uiTransform={{
+		          width: "auto",
+		          height: "auto",
+		          alignSelf: "center",
+		          margin: { top: 10 * scaleFactor, bottom: 10 * scaleFactor },
+		        }}
+	      />
+	</UiEntity>
+))
+```
+
+Some other best practices regarding UI sizes:
+
+- If the width or height of any UI element is dynamic, it's good to also use the `maxWidth`, `minWidth`, `maxHeight`, and `minHeight` parameters to make sure they stay within reasonable values.
+- The font size of text is relative to a fixed number of pixels, you should make it dynamic so it remains readable on retina displays. See [Responsive text size]({{< ref "/content/creator/sdk7/2d-ui/ui_text.md#responsive-text-size">}})
+