{"_id":"@beland/ui-scene-utils","_rev":"2-f7b5eeae89c289c85a756f8b142215cf","name":"@beland/ui-scene-utils","dist-tags":{"latest":"0.0.3-development"},"versions":{"0.0.1-development":{"name":"@beland/ui-scene-utils","version":"0.0.1-development","description":"A collection of UI helpers to make it easier to build a Beland scene using the SDK.","main":"./dist/index.js","typings":"./dist/index.d.ts","belandLibrary":{},"scripts":{"semantic-release":"semantic-release","build":"rollup -c --environment BUILD:production","link":"npm link && rollup --watch -c --environment BUILD:production"},"repository":{"type":"git","url":"git+https://github.com/belandproject/beland-ui-utils.git"},"prettier":{"printWidth":100,"singleQuote":true,"semi":false},"keywords":[],"author":{"name":"Beland"},"license":"Apache-2.0","bugs":{"url":"https://github.com/belandproject/beland-ui-utils/issues"},"homepage":"https://github.com/belandproject/beland-ui-utils#readme","devDependencies":{"prettier":"^1.19.1","semantic-release":"^16.0.1","typescript":"^3.9.3","rollup":"^2.35.1","rollup-plugin-commonjs":"^10.1.0","rollup-plugin-node-resolve":"^5.2.0","rollup-plugin-terser":"^7.0.2","rollup-plugin-typescript2":"^0.29.0","beland-ecs":"latest"},"publishConfig":{"access":"public"},"_id":"@beland/ui-scene-utils@0.0.1-development","_nodeVersion":"16.14.2","_npmVersion":"8.5.0","dist":{"integrity":"sha512-dFtbi8bbYDyB6UICm28odTON0ATHXnlpNv/7Z4xoOYt0cBO/NTtZi9as95/bk5e67C7MW5bVyM35+0z/QLM3Hg==","shasum":"771dd557f00ed6fa71cc63aec41c7ac7c5bfce64","tarball":"https://registry.npmjs.org/@beland/ui-scene-utils/-/ui-scene-utils-0.0.1-development.tgz","fileCount":28,"unpackedSize":404533,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDBgCtZGS2L0AgCdPzwE25ZqOnl3Ttf6e/LNHNGjLHVrwIhALzgk+1okoYKqZwKMXnPrdSbujqCczDZcodRZ0MdNj0J"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJisICeACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpDbQ/7BjqLHhuGmYDoUOjO+oKVpGuilhITza19UYOICx+z9ODjqL26\r\nMgmxd4h1otQhZKI1UsldvTXFpjVucVWXjqsok6FqSR2lmHCdVjydzV9ZfG9r\r\nlZAo+8S/eKp5eshamxMSJIp/mu5Uhjo6+n64K1AZIVtwXK3a6tIOId9Xp/xX\r\nMUw2oGe+/ckeG5xxN9DKhHQzWolpyKXkZKiFrcgQ0Dy8jeqUOK4ZYK6GsdHH\r\nNaPnQWjwS5smRB72mGlPOXGDSzlvHWkycbpVaEv3KI9MHj/vAU74qjZrkAxU\r\n+nWbE1pZb8B6RWVHfgv0QmW9z5yjvNQTDQvDnhXdGU2sGCtAZZbQmu57F7WP\r\nKpNsaprSqsT3tZ9BdtPt5G0UsaI/q0vkBh93p/a7LUJ9UKCrUIUmgFKBNP7Q\r\n4CS3zVFBKwBmibHjLTgo6Ex64eEwhimokXrfA0a5UiiFfEOTN702UafuAbqI\r\ntxMHqHq50jT5q52nUj8eYvkWmWWpelSMVmj8uF8G8mqRoKg2xBEDmO5wpx+z\r\nv5JQdiu3DSiqS6FtasI5FlyMrd4OPh9/7DcyS03hjUtJq+P+qVFJZnk34pC1\r\nHzRNqhMVbU7R9zKdylJTJ7y0bNyCiAxStV4onsvj4KaNjqKksqBxFSh1iRxl\r\ndQhmzMYL9qQG8FLaiMmxQ4WfWvTQcar2bSI=\r\n=fzEU\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"beland","email":"beland.developer@gmail.com"},"directories":{},"maintainers":[{"name":"beland","email":"beland.developer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ui-scene-utils_0.0.1-development_1655734430564_0.6620602241152005"},"_hasShrinkwrap":false},"0.0.2-development":{"name":"@beland/ui-scene-utils","version":"0.0.2-development","description":"A collection of UI helpers to make it easier to build a Beland scene using the SDK.","main":"./dist/index.js","typings":"./dist/index.d.ts","belandLibrary":{},"scripts":{"semantic-release":"semantic-release","build":"rollup -c --environment BUILD:production","link":"npm link && rollup --watch -c --environment BUILD:production"},"repository":{"type":"git","url":"git+https://github.com/belandproject/beland-ui-utils.git"},"prettier":{"printWidth":100,"singleQuote":true,"semi":false},"keywords":[],"author":{"name":"Beland"},"license":"Apache-2.0","bugs":{"url":"https://github.com/belandproject/beland-ui-utils/issues"},"homepage":"https://github.com/belandproject/beland-ui-utils#readme","devDependencies":{"prettier":"^1.19.1","semantic-release":"^16.0.1","typescript":"^3.9.3","rollup":"^2.35.1","rollup-plugin-commonjs":"^10.1.0","rollup-plugin-node-resolve":"^5.2.0","rollup-plugin-terser":"^7.0.2","rollup-plugin-typescript2":"^0.29.0","beland-ecs":"latest"},"publishConfig":{"access":"public"},"gitHead":"39196d2c3017946818344f6ff4ab34086bdc9638","_id":"@beland/ui-scene-utils@0.0.2-development","_nodeVersion":"16.14.2","_npmVersion":"8.5.0","dist":{"integrity":"sha512-j6d+ZpyQm4ARY2WKgbbMEgysl56mf1rK4JmcsoXzP1atG0pRta5Eu2A1kCbZ47f2KtVBZ68upkmx6hdgqLBtDQ==","shasum":"c67c27d54e2ed5f94373b9022070c9a728cde6b4","tarball":"https://registry.npmjs.org/@beland/ui-scene-utils/-/ui-scene-utils-0.0.2-development.tgz","fileCount":28,"unpackedSize":404505,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDlYPe/V/mLzEnZuc2bDBXfHCrnrt7oq/kCyeChv0AspQIhANKuAbrGNHQLv75He3+98hkFwdp30wO/vDQkAQkxgciB"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjDdPTACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpQZxAAmDpldsGXoG/YFKvYk82pJYTPfljGWc4uio2o5/bNbXclpYuh\r\n5gM2peeQfkyui5BJWU3FXvfCwySAzcza70jJRsVD5Hrk8Bhwvt9d7JifBKY1\r\n9RCs2Gas/AIaUaVToGHifHRlW6IJy5f+Fw3ZfR4jLOfG1lJ/sofa2CgJXA/C\r\nf71R7vo/C6MaWSfwN6S7IJRbVct8Lv4KYXh9aE59zgOZnwKAJ7fmprDU1Sm1\r\nO5YhE8GR7o9bII+hUGdyFkPXIsgk9tgRoNijnzXF9mbsuHsJNxp+H3AlqvC+\r\noca42fQtBCidmbBw8dhnGneHJIxnQ54Zdp4o7QbY5sZSSJR+mNcPhax1uepr\r\nSlWPltlyh+6DpEGlifXWkCDzsLx/vlvbr72s+hLb3XLUsGSXBQ3xa9eFpccu\r\nhDB/ljg9sCHLmFds5F+fW2Sd1XtpyGXSuglLkOqKOwcGDD27OSboWJxxvAOj\r\ndMCmv2zPqg+bclac89YeI81TlWQiExx9ihQPCoDVsWQQdZzrtkn/ntW4nhUv\r\nbpSHOSZeNb8RTJetwxRIUrj+Uv6blLcJndu6chUxViF0fixoHWDxaUsoORur\r\no7C9PK+0GKrvXwRoPDgONp6P930afu+tG0bdQpH5tO5b+wU8KwVJCexuzgOf\r\nDYzG2MwiZuDlhRdn3TU2YsdaJ+uCu7vaLJk=\r\n=JQxd\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"beland","email":"beland.developer@gmail.com"},"directories":{},"maintainers":[{"name":"beland","email":"beland.developer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ui-scene-utils_0.0.2-development_1661850579072_0.24697905580812707"},"_hasShrinkwrap":false},"0.0.3-development":{"name":"@beland/ui-scene-utils","version":"0.0.3-development","description":"A collection of UI helpers to make it easier to build a Beland scene using the SDK.","main":"./dist/index.js","typings":"./dist/index.d.ts","belandLibrary":{},"scripts":{"semantic-release":"semantic-release","build":"rollup -c --environment BUILD:production","link":"npm link && rollup --watch -c --environment BUILD:production"},"repository":{"type":"git","url":"git+https://github.com/belandproject/beland-ui-utils.git"},"prettier":{"printWidth":100,"singleQuote":true,"semi":false},"keywords":[],"author":{"name":"Beland"},"license":"Apache-2.0","bugs":{"url":"https://github.com/belandproject/beland-ui-utils/issues"},"homepage":"https://github.com/belandproject/beland-ui-utils#readme","devDependencies":{"prettier":"^1.19.1","semantic-release":"^16.0.1","typescript":"^3.9.3","rollup":"^2.35.1","rollup-plugin-commonjs":"^10.1.0","rollup-plugin-node-resolve":"^5.2.0","rollup-plugin-terser":"^7.0.2","rollup-plugin-typescript2":"^0.29.0","beland-ecs":"latest"},"publishConfig":{"access":"public"},"gitHead":"f19a8e584480242d6ab4c30863f1ae300bf3b733","_id":"@beland/ui-scene-utils@0.0.3-development","_nodeVersion":"16.14.2","_npmVersion":"8.5.0","dist":{"integrity":"sha512-e7p95idyc5GVqaf2GObLdYWMbJuS4cf3MFF1gBvWaBx73TCuQgsNVq30I1LirEXZR2NIRBxSapMQVKlrxyjR8A==","shasum":"7f63c2ca10dc36a6be5652700beb2dd56179b678","tarball":"https://registry.npmjs.org/@beland/ui-scene-utils/-/ui-scene-utils-0.0.3-development.tgz","fileCount":28,"unpackedSize":404505,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDGuEiuQ3EZKAbG6BZ8oj5KUcA4VBkUvK94zKffq1Y6xgIhAPqGwvj8diEbBb0oqNowj3HWFSL9SPD1GmCRW1LJFmf9"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjDd0gACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmq6vw//RnfYbrv68zp10Uy+hmgSjUt6W8jul1nnkiDbH+jxp3dDiFtz\r\nn6WLCmBGzJv/U57rONd5vLjfxkCtKsSjgM3hbbH210xKLSMEaLYqY57Fvbw7\r\nafZtfB3V8hUViQHfV5VNa7dVKNJ9lDY3X0Exa+ZJqQp5VN8aum0Pe22EEWiP\r\nf64vy6fkEgd+HFKoAy7zZwFzIRMVi7LdD4Ngiy29oFTs2aXQlWdB2dX4Fev+\r\nUIp/HwhHPFcbqk0vOZrWMsdCJAx/6ED+Vyr2IfyR0selJn6/dHfuW7Gpy89m\r\nGNQWK6oOTTU4He0nYeKnpTc9CbuOLiCrYcHIluJiqIJqm37/oV7ysAPYXaKV\r\nwkQjoQefW8nmyVi/V4VNKsWrpRfAmf1JJgELV12WTri/LxvkR173ZrFcLO+F\r\ndMF7DQD6gbzQqQUj99HhhgjN5zcEpy0Nw//ST6OgH6gENI6GNvgNsjUfWr1i\r\ndtuV8LVBzHQp9yvL4T7zMPVSzWoru2MJ6kiwtBvoefzZrfwSOHZZX4aKk2d5\r\nHJxKEunUicg93hnU/LEFKgJXeOZjJEZg1VFgyirRLclHXUTxzRXRpAAysfyZ\r\neE9no04veWcYT9Wuxs+N9Cl4kmiDWyUJqMGN0fgF3Xk4PSkWHdLSZIQvs4jg\r\nMVJkYYqi/CrqPdRQcUPc7rxiFAMtuwYyrsI=\r\n=WTIh\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"beland","email":"beland.developer@gmail.com"},"directories":{},"maintainers":[{"name":"beland","email":"beland.developer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ui-scene-utils_0.0.3-development_1661852960706_0.5891413717503595"},"_hasShrinkwrap":false}},"time":{"created":"2022-06-20T14:13:50.483Z","0.0.1-development":"2022-06-20T14:13:50.764Z","modified":"2022-08-30T09:49:20.996Z","0.0.2-development":"2022-08-30T09:09:39.273Z","0.0.3-development":"2022-08-30T09:49:20.908Z"},"maintainers":[{"name":"beland","email":"beland.developer@gmail.com"}],"description":"A collection of UI helpers to make it easier to build a Beland scene using the SDK.","homepage":"https://github.com/belandproject/beland-ui-utils#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/belandproject/beland-ui-utils.git"},"author":{"name":"Beland"},"bugs":{"url":"https://github.com/belandproject/beland-ui-utils/issues"},"license":"Apache-2.0","readme":"# UI-library\n\nA collection of tools for common UI requirements for Beland scenes.\n\nTo use any of the helpers provided by the UI utils library:\n\n1. Install the library as an npm package. Run this command in your scene's project folder:\n\n```\nnpm i @beland/ui-scene-utils -B\n```\n\n2. Run `bld start` or `bld build` so the dependencies are correctly installed.\n\n3. Import the library into the scene's script. Add this line at the start of your `game.ts` file, or any other TypeScript files that require it:\n\n```ts\nimport * as ui from '@beland/ui-scene-utils'\n```\n\n4. In your TypeScript file, write `ui`. and let the suggestions of your IDE show the available helpers.\n\n## Text Announcement\n\nTo display a text announcement on the center of the screen for a specified amount of time, use the `displayAnnouncement` function.\n\n```ts\nui.displayAnnouncement('Hello world')\n```\n\n\n\nThis function can take the following parameters:\n\n- `value`: String to display\n- `duration`: Time to keep the text visible (in seconds). Default: 3 seconds. If set to -1, the announcement will remain on screen till it's hidden.\n- `silent`: By default the `displayAnnouncement` function plays a notification sound when the text appears. If this flag is true, the sound is avoided.\n- `color`: Text color, as a _Color4_, default: yellow.\n- `size`: Font size, default: 50\n- `bordersOff`: The text has a thin black margin unless this field is set to _true_.\n\n```ts\nui.displayAnnouncement('Ouch!', 5, true, Color4.Red(), 50, true)\n```\n\nTo hide any open announcements, you can call `hideAnnouncements()`.\n\n```ts\nui.hideAnnouncements()\n```\n\n## Counter\n\nTo display a number on a corner of the screen that can be easily updated, you can create a `Counter`.\n\n```ts\nlet ammo = new ui.UICounter(30)\n```\n\n\n\nWhen instancing a new counter you can pass the following parameters:\n\n- `value`: Starting value\n- `xOffset`: Offset on X away from the bottom-left corner\n- `yOffset`: Offset on Y away from the bottom-left corner\n- `color`: Text color, white by default\n- `size`: Text size, 25 by default\n- `bordersOff`: The text has a thin black margin unless this field is set to _true_.\n\n```ts\nlet ammo = new ui.UICounter(30, 0, 60, Color4.Yellow(), 30, true)\n```\n\nOnce a `UICounter` object is instanced, you can call the following functions on it:\n\n- `read`: Returns the current value of the counter\n- `increase`: Increases the number by a given amount. If no parameters are passed, it raises the value by 1.\n- `decrease`: Decreases the number by a given amount. If no parameters are passed, it lowers the value by 1.\n- `set`: Sets the number to a given amount, no matter what the previous value was.\n\n```ts\nmyEntiy.addComponent(new OnPointerDown(e => {\n if (ammo.read() <= 0) return\n ammo.decrease()\n})\n```\n\n## Corner Labels\n\nTo display text on the bottom-left corner of the screen, you can create a `CornerLabel`.\n\n```ts\nlet healthLabel = new ui.CornerLabel('Health:')\n```\n\nWhen instancing a new corner label you can pass the following parameters:\n\n- `value`: Text to show.\n- `xOffset`: Offset on X, relative to the bottom-right corner.\n- `yOffset`: Offset on Y, relative to the bottom-right corner.\n- `color`: Text color, white by default\n- `size`: Text size, 25 by default\n- `bordersOff`: The text has a thin black margin unless this field is set to _true_.\n\n## Bar\n\nTo display a bar that can be updated to increase or shorten in length, similar to a typical health bar in games, you can create a `UIBar`.\n\n```ts\nlet health = new ui.UIBar(0.8)\n```\n\n\n\nWhen instancing a new bar you can pass the following parameters:\n\n- `value`: Starting value of the bar, from 0 to 1. With 1 the bar is full, with 0 it's empty.\n- `xOffset`: Offset on X away from the bottom-left corner.\n- `yOffset`: Offset on Y away from the bottom-left corner.\n- `fillColor`: Color of the bar filling, red by default.\n- `style`: Margin style of the bar, from a list of different predetermined options in different colors and shapes. It takes a value from the `BarStyles` enum.\n- `scale`: Multiplier to alter the size of the bar proportionally. A scale of 1 = 128 x 32 pixels.\n\n```ts\nlet health = new ui.UIBar(1, -30, 130, Color4.Red(), ui.BarStyles.ROUNDSILVER, 1)\n```\n\nOnce a `UIBar` object is instanced, you can call the following functions on it:\n\n- `read`: Returns the current value of the counter.\n- `increase`: Increases the number by a given amount. If no parameters are passed, it raises the value by 0.1.\n- `decrease`: Secreases the number by a given amount. If no parameters are passed, it lowers the value by 0.1.\n- `set`: Sets the bar to a given value, no matter what the previous value was.\n\n```ts\nmyEntiy.addComponent(new OnPointerDown(e => {\n\thealth.decrease(0.1)\n\tif (health.read() <= 0) {\n\t\t// die\n\t}\n})\n```\n\n## Corner Icons\n\nTo display an icon of on the bottom-left corner of the screen you can create one of the following:\n\n- `SmallIcon`: by default 32x32 pixels in size.\n- `MediumIcon`: by default 64x64 pixels in size.\n- `LargeIcon`: by default 128x128 pixels in size.\n\n```ts\nlet healthIcon = new ui.MediumIcon('images/heart64.png')\n```\n\n\n\nWhen instancing a new icon you can pass the following parameters:\n\n- `image`: Path to the image file.\n- `xOffset`: Offset on X, relative to the bottom-right corner.\n- `yOffset`: Offset on Y, relative to the bottom-right corner.\n- `width`: Image width on screen in pixels.\n- `height`: Image height on screen in pixels.\n- `section`: Use only a section of the image file, useful when arranging multiple icons into an image atlas. This field takes an `ImageSection` object, specifying `sourceWidth` and `sourceHeight`, and optionally also `sourceLeft` and `sourceTop`.\n\n```ts\nlet ammoIcon = new ui.SmallIcon('images/ammo32.png', -70, 70)\nlet healthIcon = new ui.MediumIcon('images/heart64.png', -170, 120)\n```\n\n## Loading icon\n\nTo display a loading icon on the center of the screen for a specified amount of time, create a `LoadingIcon`.\n\n```ts\nloading = new ui.LoadingIcon(3)\n```\n\n\n\nWhen instancing a new loading icon, you can pass the following parameters:\n\n- `duration`: seconds to display the image onscreen. If not set, or set to 0, it keeps the icon on till you hide it.\n- `xOffset`: Offset on X, relative to the center of the screen.\n- `yOffset`: Offset on Y, relative to the center of the screen.\n- `scale`: Multiplier to alter the size of the icon proportionally. A scale of 1 = 48 x 64 pixels.\n\n```ts\nloading = new ui.LoadingIcon(3, 0, 40, 0.5)\n```\n\nOnce a `LoadingIcon` object is instanced, you can call the `hide()` function to remove it.\n\n## Full screen image\n\nTo display a large image on the center of the screen for a spefified amount of time, create a `CenterImage`. By default images must be 512 x 512 pixels, unless specified.\n\n```ts\nlet largeImage = new ui.CenterImage('images/Burn.png')\n```\n\nWhen instancing a new large image, you can pass the following parameters:\n\n- `image`: Path to image file.\n- `duration`: Seconds to display the image onscreen, 3 seconds by default. -1 keeps it on till you hide it.\n- `startHidden`: If true, the image starts invisible till you run its `show()` function. Large images may flash white for a second if created and shown at the same time. By deferring the creation you avoid this artifact.\n- `xOffset`: Offset on X, relative to the center of the screen.\n- `yOffset`: Offset on Y, relative to the center of the screen.\n\n* `width`: Image width on screen in pixels, 512 by default.\n* `height`: Image height on screen in pixels, 512 by default.\n* `section`: Use only a section of the image file, useful when arranging multiple images into an image atlas. This field takes an `ImageSection` object, specifying `sourceWidth` and `sourceHeight`, and optionally also `sourceLeft` and `sourceTop`.\n\n```ts\nlet gameOver = new ui.CenterImage('images/Burn.png', 3, true, 0, 0, 512, 512, {\n sourceHeight: 512,\n sourceWidth: 512,\n sourceLeft: 0,\n sourceTop: 0\n})\ngameOver.show()\n```\n\nOnce a `CenterImage` object is instanced, you can call the following functions on it:\n\n- `show`: Shows the image.\n- `hide`: Hides the image.\n\n## Predefined prompt windows\n\nThe UI Utils library includes various common prompt windows to display messages and ask players to take action.\n\n### Ok Prompt\n\nDisplays a prompt window with a custom message and an OK button. The Ok button can either be clicked or triggered by pressing the E key.\n\nWhen instancing a new Ok Prompt, you can pass the following parameters:\n\n- `instructions`: Message string.\n- `onAccept`: Function that gets executed if player clicks the button or presses E.\n- `acceptLabel`: Label to go in the accept button, \"Ok\" by default.\n- `useDarkTheme`: Switch the style of the window to the dark theme.\n\n```ts\nlet prompt = new ui.OkPrompt(\n 'This is an Ok Prompt',\n () => {\n log(`accepted`)\n },\n 'Ok',\n true\n)\n```\n\n\n\n> Note: If the player closes the window with the close icon, the related function isn't called.\n\n### Option Prompt\n\nDisplays a prompt window with a custom message, a title, and two buttons that perform separate actions. The buttons can be clicked or triggered by the E and F keys.\n\nWhen instancing a new Option Prompt, you can pass the following parameters:\n\n- `title`: Header in bold letters at the top of the window\n- `instructions`: Smaller print instructions.\n- `onAccept`: Function that gets executed if player clicks accept.\n- `onReject`: Function that gets executed if player clicks reject.\n- `acceptLabel`: String to go in the accept button\n- `rejectLabel`: String to go in the reject button\n- `useDarkTheme`: Switch the style of the window to the dark theme.\n\n```ts\nlet prompt = new ui.OptionPrompt(\n 'Pick an option!',\n 'What will you choose?',\n () => {\n log(`picked option A`)\n },\n () => {\n log(`picked option B`)\n },\n 'Pick A',\n 'Pick B'\n)\n```\n\n\n\n> Note: If the player closes the window with the close icon, neither of the functions are called.\n\n### Fill in Prompt\n\nDisplays a prompt window with a header, a text field to fill in and a submit button. The value filled into the text box can be used as a parameter in the submit function.\n\nWhen instancing a new Fill-in Prompt, you can pass the following parameters:\n\n- `title`: Header in bold letters at the top of the window.\n- `onAccept`: Function that gets executed when player clicks button of presses the E key.\n- `acceptLabel`: String to use as label on the submit button. \"Submit\" by default.\n- `placeholder`: Text to display as placeholder in the text box.\n- `useDarkTheme`: Switch the style of the window to the dark theme.\n\n```ts\nlet prompt = new ui.FillInPrompt(\n 'What are you thinking?',\n (e: string) => {\n log(e)\n },\n 'Submit!',\n 'Text goes here'\n)\n```\n\n\n\n> Note: If the player closes the window with the close icon, the related function isn't called.\n\n## Custom Prompt Windows\n\nCustom prompt windows let you arrange as many elements as you want into a window, including buttons, text, checkboxes, switches, textboxes and icons.\n\n### Create a custom prompt\n\nFirst create a new `CustomPrompt` object.\n\n```ts\nlet prompt = new ui.CustomPrompt(ui.PromptStyles.DARKSLANTED)\n```\n\n\n\nWhen instancing a new loading icon, you can pass the following parameters:\n\n- `style`: Pick from a few predefined options, some of them using the dark theme, others the light theme. You can also provide a string with a path to a custom image to use as a background instead.\n- `width`: Background width on screen in pixels. The default size depends on the theme used.\n- `height`: Background height on screen in pixels. The default size depends on the theme used.\n- `startHidden`: If true, image starts invisible to load in the background till calling the `show()` function of the prompt object.\n\n> Note: Stretching the background images away from their default values may lead to blurry corners.\n\nOnce you instanced a `CustomPrompt` object, you can add elements to it by calling its various functions.\n\nYou can also call the following functions on it:\n\n- `hide`: Hides the window.\n- `show`: Shows the window if previously closed.\n\nAccess all of the UI elements that make up the prompt UI by calling the `elements` property of the prompt object.\n\n### Add Text\n\nTo add text to a custom prompt, use the `addText` function.\n\n```ts\nlet myText = prompt.addText('Hello World', 0, 100)\n```\n\nThe `addText()` function can take the following parameters:\n\n- `value`: Text to show.\n- `posX`: Offset on X from the center of the window.\n- `posY`: Offset on Y from the center of the window.\n- `color`: Text color.\n- `size`: Text size.\n\nThe `addText()` function returns a `CustomPromptText` object, that you can then reference to change its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n\n### Add a button\n\nTo add a button to a custom prompt, use the `addButton` function.\n\n```ts\nlet myButton = prompt.addButton(\n 'Yes',\n 0,\n -30,\n () => {\n log('Yes')\n prompt.hide()\n },\n ui.ButtonStyles.E\n)\n```\n\nThe `addButton` function can take the following parameters:\n\n- `label`: Label to show on the button.\n- `posX`: Offset on X from the center of the window.\n- `posY`: Offset on Y from the center of the window.\n- `onClick`: Function to execute when the button is clicked.\n- `style`: Choose out of several predefined style options, with different colors and rounded or square corners.\n\n> Note: If you pick the `E` or `F` style, the buttons will also be triggered when pressing the E or F keys respectively.\n\n\n\nThe `addButton()` function returns a `CustomPromptButton` object, that you can then reference to change its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n- `grayOut`: Sets the text to gray and makes it unclickable.\n- `enable`: Sets the text to white and makes it clickable again.\n\n### Add a Checkbox\n\nTo add a checkbox to a custom prompt, use the `addCheckbox` function.\n\n```ts\nlet myCheckbox = prompt.addCheckbox(\n \"Don't show again\",\n -80,\n 50,\n () => {\n log('checkbox ticked')\n },\n () => {\n log('checkbox unticked')\n }\n)\n```\n\nThe `addCheckbox` function can take the following parameters:\n\n- `label`: Label to show next to the checkbox.\n- `posX`: Offset on X from the center of the window.\n- `posY`: Offset on Y from the center of the window.\n- `onCheck`: Function to execute when the box is checked.\n- `onUncheck`: Function to execute when the box is unchecked.\n- `large`: The default size of the checkbox is 24 x 24 pixels, checking this box sets the size to 32 x 32.\n- `startChecked`: If true, the box starts checked by default.\n\nThe `addCheckbox()` function returns a `CustomPromptCheckbox` object, that you can then reference to change and read its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n- `check`: Sets the element to checked, without performing the associated function.\n- `uncheck`: Sets the element to checked, without performing the associated function.\n\nYou can also read the returned object's `checked` property at any time to find its current state.\n\n### Add a Switch\n\nTo add a switch to a custom prompt, use the `addSwitch` function.\n\n```ts\nlet mySwitch = prompt.addSwitch(\n 'Turn on',\n -80,\n 50,\n () => {\n log('switch activated')\n },\n () => {\n log('switch deactivated')\n },\n ui.SwitchStyles.SQUAREGREEN\n)\n```\n\nThe `addSwitch` function can take the following parameters:\n\n- `label`: Label to show next to the switch.\n- `posX`: Offset on X from the center of the window.\n- `posY`: Offset on Y from the center of the window.\n- `onCheck`: Function to execute when the switch is activated.\n- `onUncheck`: Function to execute when the switch is deactivated.\n- `style`: Pick between several sizes, with different colors and rounded or square corners. The value must be from the `SwitchStyles` enum.\n- `startChecked`: If true, the switch starts activated by default.\n\n\n\nThe `addSwitch()` function returns a `CustomPromptSwitch` object, that you can then reference to change and read its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n- `check`: Sets the element to checked, without performing the associated function.\n- `uncheck`: Sets the element to checked, without performing the associated function.\n\nYou can also read the returned object's `checked` property at any time to find its current state.\n\n### Add an icon\n\nTo add an icon to a custom prompt, use the `addIcon` function.\n\n```ts\nlet myIcon = prompt.addIcon(`images/icon.png`, -50, 0, 64, 64)\n```\n\nThe `addIcon` function can take the following parameters:\n\n- `image`: Path to the image file.\n- `xOffset`: Offset on X, relative to the window's center.\n- `yOffset`: Offset on Y, relative to the window's center.\n- `width`: Image width on screen in pixels.\n- `height`: Image height on screen in pixels.\n- `section`: Use only a section of the image file, useful when arranging multiple icons into an image atlas. This field takes an `ImageSection` object, specifying `sourceWidth` and `sourceHeight`, and optionally also `sourceLeft` and `sourceTop`.\n\nThe `addIcon()` function returns a `CustomPromptIcon` object, that you can then reference to change its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n\n### Add an input box\n\nTo add an input box to a custom prompt, use the `addTextBox` function.\n\n```ts\nlet myInput = prompt.addTextBox(`images/icon.png`, 0, 30)\n```\n\nThe `addTextBox` function can take the following parameters:\n\n- `posX`: Offset on X, relative to the window's center.\n- `posY`: Offset on Y, relative to the window's center.\n- `placeholder`: Text to display in the input box before the player interacts with it.\n- `onChange`: Function that gets executed every time the player edits the content on the input box, once for each character changed.\n\nThe `addTextBox()` function returns a `CustomPromptTextBox` object, that you can then reference to change and read its values. This object also has the following functions that can be called any time:\n\n- `hide`\n- `show`\n\nYou can access the last edited value on the textbox by fetching the `currentText` value of the returned object.\n\n### Full Custom UI example\n\nHere's a full example of a custom UI:\n\n```ts\nlet prompt = new ui.CustomPrompt(ui.PromptStyles.DARKSLANTED)\nprompt.addText('What will you do?', 0, 130, Color4.Red(), 30)\nprompt.addText(\"It's an important decision\", 0, 100)\n\nlet checkBox = prompt.addCheckbox(\"Don't show again\", -80, 50)\n\nlet button1 = prompt.addButton(\n 'Yeah',\n 0,\n -30,\n () => {\n log('Yes')\n prompt.hide()\n },\n ui.ButtonStyles.E\n)\n\nlet button2 = prompt.addButton(\n 'Nope',\n 0,\n -90,\n () => {\n log('No')\n prompt.hide()\n },\n ui.ButtonStyles.F\n)\n```\n\n\n\n---\n\n## Contribute\n\nIn order to test changes made to this repository in active scenes, do the following:\n\n1. Run `npm run link` on this repository\n2. On the scene directory, after you installed the dependency, run `npm link @beland/ui-scene-utils`\n\n## CI/CD\n\nThis repository uses `semantic-release` to atumatically release new versions of the package to NPM.\n\nUse the following convention for commit names:\n\n`feat: something`: Minor release, every time you add a feature or enhancement that doesn’t break the api.\n\n`fix: something`: Bug fixing / patch\n\n`chore: something`: Anything that doesn't require a release to npm, like changing the readme. Updating a dependency is **not** a chore if it fixes a bug or a vulnerability, that's a `fix`.\n\nIf you break the API of the library, you need to do a major release, and that's done a different way. You need to add a second comment that starts with `BREAKING CHANGE`, like:\n\n```\ncommit -m \"feat: changed the signature of a method\" -m \"BREAKING CHANGE: this commit breaks the API, changing foo(arg1) to foo(arg1, arg2)\"\n```\n","readmeFilename":"README.md"}