Touch

Showcase Community Content
1

Cover
Cover1920×1080 51.5 KB

TEMPLATE NAME: Touch
CORE VERSION: 1.0.294
TEMPLATE VERSION: 1.0.0

TEMPLATE DESCRIPTION:

Flexible micro-framework for adding behavior to any template when it's interacted with. Includes support for tap, and longpress (hold) input gestures.

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, and replaced by a more-modular framework that will support multiple interactions for each template

TEMPLATE VERSION NOTES:

Version 1.0.0

  • First stable release.

ADDITIONAL INFO:

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

Getting Started

Import

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

Set Up

  1. In Project Content, select the "Imported Content > Touch > Dependent Scripts" group.
  2. Add the "Touch_TouchConfigurationStatic" script to the Hierarchy, in Static Context.
  3. Add the "Touch_TouchStartClient" script to the Hierarchy, in Client Context.
  4. In the Hierarchy, select the "Touch_TouchStartClient" script instance; then drag the "Touch_TouchConfigurationStatic" script instance (from the Hierarchy) into the "Touch_TouchStartClient" script instance's "Configuration" custom property (in the Properties panel).
  5. Add a Pointer Adapter script. (See "Create an Adapter".)
  6. Add Handler scripts. (See "Create a Handler".)
  7. Add Catalog data tables and scripts. (See "Create a Catalog".)

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 "TouchService"; then set its default value to reference the "Touch_TouchService" script.
  3. Edit the script that will be using the Service; at or near the top of the code, add…
    local TouchService = require(script:GetCustomProperty("TouchService"))

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

Create an Adapter

Use an Adapter to integrate this Service with other frameworks or code.

  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 > Touch > Dependent Scripts" group, then browse to the "Example" folder.
  4. Right-click an example Adapter 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 Adapter script (if applicable), and configure their default values.
  6. Add the new Adapter script to the Hierarchy, as a child of the "Touch_TouchStartClient" script instance.
  7. Edit the new Adapter script, to implement its relevant hook functions. (See "Adapters" API reference.)

Use an Existing Adapter

Use an Adapter to integrate this Service with other frameworks or code.

  1. In Project Content, browse to the existing Adapter script.
  2. Add the existing Adapter script to the Hierarchy, as a child of the "Touch_TouchStartClient" script instance.
  3. Configure the new Adapter script instance's "TouchService" custom property to reference the "Touch_TouchService" script.

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 > Touch > 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 "Touch_TouchStartClient" 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 "Touch_TouchStartClient" script instance.
  3. Configure the new Handler script instance's "TouchService" custom property to reference the "Touch_TouchService" script.
  4. Configure the new Handler script instance's "GroupId" custom property.

Create a Catalog

Use a Catalog to register templates, game objects, or ID's with this Service, and associate each entry with static game data.

  1. In Project Content, select the "My Tables" 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 > Touch > Dependent Data Tables" group, then browse to the "Example" folder.
  4. Right-click an example Catalog data table, 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 Tables" 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. In Project Content, select the "Imported Content > Touch > Dependent Scripts" group.
  6. Add the matching Catalog script to the Hierarchy, as a child of the "Touch_TouchStartClient" script instance.
  7. If the new Catalog script instance has a "GroupId" custom property, configure that custom property.
  8. In Project Content, select the "My Tables" group, then browse to the new Catalog data table.
  9. In the Hierarchy, select the new Catalog script instance; then drag the new Catalog data table (from Project Content) into the new Catalog script instance's "Table" custom property (in the Properties panel).
  10. Edit the new Catalog data table, to add relevant game data. (See "Catalogs" data table reference.)

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 > Touch" 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 > Touch" 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 > Touch" group, and select "Delete Assets"; then click "Delete All" each time.

Custom Properties Reference

Touch_TouchStartClient

Custom Properties

AssetReference TouchService

"Touch_TouchService" 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

"Touch_TouchConfigurationStatic" script instance.

Touch_TouchConfigurationStatic

Custom Properties

float LongpressTimer

Amount of time (in seconds) an interaction must be held, before it will be interpreted as a longpress gesture.
Default: 0.5

string RequestTouchBeginEvent

Event this Service should listen for, to begin an interaction.
Default: "Touch.RequestTouchBegin"

string RequestTouchEndEvent

Event this Service should listen for, to end the current interaction.
Default: "Touch.RequestTouchEnd"

Adapters

Touch_ExampleTouchPointerAdapterClient

Custom Properties

AssetReference TouchService

"Touch_TouchService" script.

Handlers

Touch_ExampleTouchHandlerClient

Custom Properties

AssetReference TouchService

"Touch_TouchService" script.

string GroupId

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

Catalogs

Touch_TouchCatalogClient

Custom Properties

AssetReference TouchService

"Touch_TouchService" script.

string GroupId

ID of Group this Catalog registers entities and game data for. A Group can have at most one Catalog of each type.

boolean IncludePlayers

Whether players will be considered potential subjects by Handlers belonging to this Catalog's Group. At most one Catalog can have its "IncludePlayers" custom property set to true.
Default: false

AssetReference Table

Data Table that provides the entities and game data for this Catalog to register.

string GetAssetId

Data Table column for templates to register as entities.
Default: "Asset"

Data Table Reference

Catalogs

Touch_ExampleTouchCatalog

Columns

AssetReference Asset

Template to register as an entity. Instances of the template will be considered potential subjects by Handlers belonging to this Catalog's Group. The template must be unique across all Catalogs of the same type.

Script Reference

Touch_TouchServiceClient

Event Listeners (Client-Side)

nil RequestTouchBegin()

Tries to begin an interaction.
Event: (Configuration "RequestTouchBeginEvent")

nil RequestTouchEnd(boolean abort)

Tries to end the current interaction. If abort is true, the interaction will be treated as canceled (instead of voluntarily ended by the player).
Event: (Configuration "RequestTouchEndEvent")

API Reference

Configuration

Properties

float longpressTimer

Amount of time (in seconds) an interaction must be held, before it will be interpreted as a longpress gesture.

string eventRequestTouchBegin

Event this Service should listen for, to begin an interaction.

string eventRequestTouchEnd

Event this Service should listen for, to end the current interaction.

TouchService

Static Methods

TouchService Use()

Returns the singleton instance of this Service.

Methods (Accessors)

Configuration GetConfiguration()

Returns this Service's Configuration instance.

CoreObject GetSubject()
Player GetSubject()
nil GetSubject()

Returns the current CoreObject or Player that's being interacted with; otherwise, returns nil.

float GetTimer()

Returns the amount of time (in seconds) that the current interaction has been held.

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 "Touch_TouchSetupClient" script instance have finished loading.

nil AwaitStart()

Blocks execution until all scripts tracked by this Service's "Touch_TouchStartClient" 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 "Touch_TouchSetupClient" script instance have finished loading.

nil AfterStart(function thunk)

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

PointerAdapter AddPointerAdapter()

Creates, registers, and returns a new PointerAdapter instance for this Service. This Service can have at most one PointerAdapter instance.

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.

Catalog AddCatalog(string groupId, boolean includePlayers)

Creates, registers, and returns a new Catalog instance for Group groupId, for this Service. A Group can have at most one Catalog instance. If includePlayers is true, players will be considered potential subjects by Handlers belonging to the Group. At most one Catalog instance can have includePlayers set to true.

nil Suspend()

Suspends processing for this Service. The current interaction will be treated as canceled.

nil Restore()

Resumes processing for this Service.

Adapters

PointerAdapter

Methods (Hook)

HitResult GetHit()
nil GetHit()

Called by the Service when an interaction is requested, and every tick while a relevant subject is being interacted with, to get the current CoreObject or Player that's being pointed at. If a valid CoreObject or Player is being pointed at, this method should return a HitResult instance (e.g.: from Core's World.Raycast or UI.GetHitResult methods); otherwise, this method should return nil.

Handlers

Handler

Methods (Hook)

boolean CanTouch(CoreObject subject, HitResult hit)
boolean CanTouch(Player subject, HitResult hit)

Called by the Service when an interaction is requested with a potential subject, and every tick while a relevant subject is being interacted with, to query whether the subject is (still) relevant to this Handler instance. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method. If subject subject is relevant to this Handler instance, this method should return true; otherwise, this method should return false.

boolean CanTap(CoreObject subject, HitResult hit)
boolean CanTap(Player subject, HitResult hit)

Called by the Service when an interaction with a relevant subject produces a tap gesture, to query whether to trigger tap interaction behavior. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method. If tap interaction behavior should be triggered, this method should return true; otherwise, this method should return false.

boolean CanLongpress(CoreObject subject, HitResult hit)
boolean CanLongpress(Player subject, HitResult hit)

Called by the Service when an interaction with a relevant subject produces a longpress gesture, to query whether to trigger longpress interaction behavior. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method. If longpress interaction behavior should be triggered, this method should return true; otherwise, this method should return false.

nil TouchBegin(CoreObject subject, HitResult hit)
nil TouchBegin(Player subject, HitResult hit)

Called by the Service when a relevant subject is interacted with. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method.

nil Touch(CoreObject subject, HitResult hit)
nil Touch(Player subject, HitResult hit)

Called by the Service every tick, while a relevant subject is being interacted with. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method.

nil TouchEnd(CoreObject subject, HitResult hit, boolean abort)
nil TouchEnd(Player subject, HitResult hit, boolean abort)

Called by the Service when a relevant subject ceases being interacted with, ceases being pointed at, or ceases being relevant. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method. If the interaction was canceled (instead of voluntarily ended by the player), abort will be true; otherwise, abort will be false.

nil Tap(CoreObject subject, HitResult hit)
nil Tap(Player subject, HitResult hit)

Called by the Service when an interaction with a relevant subject triggers tap interaction behavior. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method.

nil Longpress(CoreObject subject, HitResult hit)
nil Longpress(Player subject, HitResult hit)

Called by the Service when an interaction with a relevant subject triggers longpress interaction behavior. If the subject is a CoreObject, subject will be its template root; if the subject is a Player, subject will be that Player instance. hit will be the value that was returned by the Service's PointerAdapter instance's GetHit hook method.

Catalogs

Catalog

Methods

nil Add(string key)

Adds template key to this Catalog instance. key must be unique across all Catalog instances.

Examples

See "Touch" by Descendent in Community Projects.