Pointer

Showcase Community Content
1

Cover
Cover1920×1080 51.2 KB

TEMPLATE NAME: Pointer
CORE VERSION: 1.0.294
TEMPLATE VERSION: 1.0.0

TEMPLATE DESCRIPTION:

Flexible micro-framework for standardizing and caching raycasts for other code.

Based upon the concepts in Descendent's Framework Architecture, for easy integration and customization with other code.

TEMPLATE ROADMAP:

  • This framework is expected to be deprecated in the future, along with the Touch framework

TEMPLATE VERSION NOTES:

Version 1.0.0

  • First stable release.

ADDITIONAL INFO:

  • Community Content — "Pointer"
  • Community Project (example) — "Pointer"

Getting Started

Import

  1. In Community Content, search for "descendent".
  2. Browse to the listing for "Pointer", and click "Import"; then click "Yes".
  3. In Core Content, under the "Community Content" category, select the "Imported Content > Pointer" group.
  4. Add the "Pointer" template to the Hierarchy (in Default Context).

Set Up

  1. In Project Content, select the "Imported Content > Pointer > Dependent Scripts" group.
  2. Add the "Pointer_PointerConfigurationStatic" script to the Hierarchy, in Static Context.
  3. Add the "Pointer_PointerStartClient" script to the Hierarchy, in Client Context.
  4. In the Hierarchy, select the "Pointer_PointerStartClient" script instance; then drag the "Pointer_PointerConfigurationStatic" script instance (from the Hierarchy) into the "Pointer_PointerStartClient" script instance's "Configuration" custom property (in the Properties panel).
  5. Add Handler scripts. (See "Create a Handler".)

How-To Guides

Use this Service in a Script

  1. In Project Content, browse to the script that will be using the Service, and select it.
  2. In the Properties panel, add a custom property of type "Asset Reference", and name it "PointerService"; then set its default value to reference the "Pointer_PointerService" script.
  3. Edit the script that will be using the Service; at or near the top of the code, add…
    local PointerService = require(script:GetCustomProperty("PointerService"))

local _pointerService = PointerService.Use()
  4. Use this Service's singleton instance via the _pointerService variable. (See "PointerService" API reference.)

Create a Handler

Use a Handler to customize this Service with game-specific game logic.

  1. In Project Content, select the "My Scripts" group.
  2. At the top of the right frame (where the "Search" field is), click the :open_file_folder: ("Create Folder") button; enter "Example", and press Enter.
  3. In Project Content, select the "Imported Content > Pointer > Dependent Scripts" group, then browse to the "Example" folder.
  4. Right-click an example Handler script, and select "Duplicate Asset"; then rename the new copy to an appropriate name, and move it to an appropriate folder.
    • The new copy will initially be placed in the "My Scripts" group, in the "Example" folder, and have " - Copy" appended to its name; if the "Example" folder or the new copy doesn't appear in Project Content, save, close, and re-open the project.
  5. Add custom properties to the new Handler script (if applicable), and configure their default values.
  6. Add the new Handler script to the Hierarchy, as a child of the "Pointer_PointerStartClient" script instance.
  7. Configure the new Handler script instance's "GroupId" custom property.
  8. Edit the new Handler script, to implement its relevant hook functions. (See "Handlers" API reference.)

Use an Existing Handler

Use a Handler to customize this Service with game-specific game logic.

  1. In Project Content, browse to the existing Handler script.
  2. Add the existing Handler script to the Hierarchy, as a child of the "Pointer_PointerStartClient" script instance.
  3. Configure the new Handler script instance's "PointerService" custom property to reference the "Pointer_PointerService" script.
  4. Configure the new Handler script instance's "GroupId" custom property.

Share an Adapter, Handler, or Binding with Other Projects or Creators

  1. In Project Content, browse to the Adapter, Handler, or Binding script that will be shared with other projects or creators, and select it.
  2. In the Properties panel, for each custom property of type "Asset Reference", "Core Object Reference", or "Net Reference": right-click the large icon in the custom property's value (or the custom property's value itself), and select "Clear Value".
    • Custom properties referencing assets or objects that shouldn't be duplicated in other projects must be cleared, to prevent the assets or objects from being packaged together with the Adapter, Handler, or Binding script when shared. These custom properties will need to be re-configured on each script instance (in the Hierarchy) in each project.
  3. Right-click the Adapter, Handler, or Binding script, and select ":rocket: Publish to Community Content"; then complete the process to publish as a public or private Community Content package.

Update

  1. In Project Content, right-click the "Imported Content > Pointer" group, and select "Download Latest"; then click "Yes"; then click "Continue with save: I accept the risk".

Delete

  1. In Project Content, right-click the "Imported Content > Pointer" group, and select "Delete Assets"; then, if asked, click "Delete All and Save" each time; then click "Delete All" each time.
  2. In Core Content, under the "Community Content" category, right-click the "Imported Content > Pointer" group, and select "Delete Assets"; then click "Delete All" each time.

Custom Properties Reference

Pointer_PointerStartClient

Custom Properties

AssetReference PointerService

"Pointer_PointerService" script.

string Await

Field in each tracked script's context that's expected to be assigned a truthy value, once the tracked script has finished loading.
Default: "ready"

float AwaitTimer

Amount of time (in seconds) to wait for each of this script instance's tracked scripts to finish loading, before logging a warning. This script instance will wait forever if the field specified by its "Await" custom property couldn't be found in a tracked script's context.
Default: 60

CoreObjectReference Configuration

"Pointer_PointerConfigurationStatic" script instance.

Handlers

Pointer_ExamplePointerHandlerClient

Custom Properties

AssetReference PointerService

"Pointer_PointerService" script.

string GroupId

ID of Group this Handler provides game logic for. A Group can have at most one Handler of each type.

API Reference

PointerService

Static Methods

PointerService Use()

Returns the singleton instance of this Service.

Methods (Accessors)

Configuration GetConfiguration()

Returns this Service's Configuration instance.

Methods

nil AwaitConfiguration()

Blocks execution until this Service's Configuration instance is initialized.

nil AwaitSetup()

Blocks execution until all scripts tracked by this Service's "Pointer_PointerSetupClient" script instance have finished loading.

nil AwaitStart()

Blocks execution until all scripts tracked by this Service's "Pointer_PointerStartClient" script instance have finished loading.

nil AfterConfiguration(function thunk)

Schedules function thunk to be called after this Service's Configuration instance is initialized.

nil AfterSetup(function thunk)

Schedules function thunk to be called after all scripts tracked by this Service's "Pointer_PointerSetupClient" script instance have finished loading.

nil AfterStart(function thunk)

Schedules function thunk to be called after all scripts tracked by this Service's "Pointer_PointerStartClient" script instance have finished loading.

Handler AddHandler(string groupId)

Creates, registers, and returns a new Handler instance for Group groupId, for this Service. A Group can have at most one Handler instance.

HitResult GetHit(string groupId)
nil GetHit(string groupId)

Returns a HitResult instance for Group groupId, if something was hit; otherwise, returns nil. The value that's returned will always be the same during the same tick, whenever this method is called with the same groupId.

Handlers

Handler

Methods (Hook)

HitResult GetHit()
nil GetHit()

Called by the Service to get a new HitResult instance. If something was hit, this method should return a HitResult instance (e.g.: from Core's World.Raycast or UI.GetHitResult methods); otherwise, this method should return nil.

Examples

See "Pointer" by Descendent in Community Projects.