Open Asterune
Query

Query

Selects Instances by components, tags, class, hierarchy, and component changes.

Behavior

Query selects Instances by components, tags, class, hierarchy, and component changes.

Summary

Constructors1
Functions1
  • Query.new(args: ...Component | string): Query

    Creates a reusable query requiring each listed component.

Members11
Methods11
  • added(component: Component | string): Query

    Returns a new query filtered to Instances whose specified component was added during the current change-tracking frame.

  • changed(component: Component | string): Query

    Returns a new query filtered to Instances whose specified component changed during the current change-tracking frame.

  • collect(): table

    Returns a new array of matching Instances.

  • count(): number

    Returns the number of Instances matching the current query filters.

  • first(): (Instance?, ...ComponentHandle)

    Returns the first matching Instance and its component handles.

  • isA(className: string): Query

    Returns a new query restricted to the named class and its subclasses.

  • removed(): table, boolean

    Returns Instances that lost one of the query's required components since the previous call, followed by a completeness boolean.

  • up(component: Component | string): Query

    Returns a new query requiring an ancestor carrying the specified component.

  • with(components: Component | string | { Component | string }): Query

    Returns a new query with additional required components or tags.

  • within(ancestor: Instance): Query

    Returns a new query restricted to descendants of the supplied Instance.

  • without(components: Component | string | { Component | string }): Query

    Returns a new query excluding Instances with any listed component or tag.

Constructors

new

Query.new(args: ...Component | string): Query

Creates a reusable query requiring each listed component. Terms accept Component definitions or component names. An unresolved required component produces no matches until it becomes available. Iteration returns the Instance followed by handles in term order.

Methods

added

Query:added(component: Component | string): Query

Returns a new query filtered to Instances whose specified component was added during the current change-tracking frame.

changed

Query:changed(component: Component | string): Query

Returns a new query filtered to Instances whose specified component changed during the current change-tracking frame.

collect

Query:collect(): table

Returns a new array of matching Instances. Component handles are not included.

count

Query:count(): number

Returns the number of Instances matching the current query filters.

first

Query:first(): (Instance?, ...ComponentHandle)

Returns the first matching Instance and its component handles. Returns nil when no Instance matches. Do not depend on iteration order.

isA

Query:isA(className: string): Query

Returns a new query restricted to the named class and its subclasses. An unknown class name causes an error.

removed

Query:removed(): table, boolean

Returns Instances that lost one of the query's required components since the previous call, followed by a completeness boolean. The result is deduplicated. A storage reset or unavailable history makes the boolean false. A query with no required components causes an error.

up

Query:up(component: Component | string): Query

Returns a new query requiring an ancestor carrying the specified component. The ancestor's component handle is appended to each returned row.

with

Query:with(components: Component | string | { Component | string }): Query

Returns a new query with additional required components or tags. Component definitions select components; strings select tags. These filters do not add returned handles.

within

Query:within(ancestor: Instance): Query

Returns a new query restricted to descendants of the supplied Instance.

without

Query:without(components: Component | string | { Component | string }): Query

Returns a new query excluding Instances with any listed component or tag. Component definitions select components; strings select tags.

Operators

__iter · __tostring · __type

Related APIs

Component · ComponentHandle