A **coroutine** is used to perform multiple tasks at the same time from within
the same script. Such tasks might include producing values from inputs or
performing work on a subroutine when solving a larger problem. A task doesn't
even need to have a defined ending point, but it does need to define
particular times at which it **yields** (pause) to let other things be worked
on.

## Using Coroutines

A new coroutine can be created by providing a function to
`Library.coroutine.create()`. Once created, a coroutine doesn't begin running
until the first call to `Library.coroutine.resume()` which passes the
arguments to the function. This call returns when the function either halts or
calls `Library.coroutine.yield()` and, when this happens,
`Library.coroutine.resume()` returns either the values returned by the
function, the values sent to `Library.coroutine.yield()`, or an error message.
If it does error, the second return value is the thrown error.

```lua
local function task(...)
	-- This function might do some work for a bit then yield some value
	coroutine.yield("first")  -- To be returned by coroutine.resume()
	-- The function continues once it is resumed again
	return "second"
end

local taskCoro = coroutine.create(task)
-- Call resume for the first time, which runs the function from the beginning
local success, result = coroutine.resume(taskCoro, ...)
print(success, result)  --> true, first (task called coroutine.yield())
-- Continue running the function until it yields or halts
success, result = coroutine.resume(taskCoro)
print(success, result)  --> true, second (task halted because it returned "second")
```

During the lifetime of the coroutine, you can call
`Library.coroutine.status()` to inspect its status:

<table>
    <thead>
        <tr>
            <th>Status</th>
            <th>Meaning</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><b>suspended</b></td> <td>The coroutine is waiting to be
            resumed. Coroutines begin in this state and enter it when their
            function calls <code>coroutine.yield()</code>.</td>
        </tr>
        <tr>
            <td><b>running</b></td>
            <td>The coroutine is running right now.</td>
        </tr>
        <tr>
            <td><b>normal</b></td> <td>The coroutine is awaiting the yield of
            another coroutine; in other words, it has resumed another
            coroutine.</td>
        </tr>
        <tr>
            <td><b>dead</b></td> <td>The function has halted (returned or
            thrown an&nbsp;error). The coroutine cannot be used further.</td>
        </tr>
    </tbody>
</table>

### Wrapping Coroutines

When working with coroutines, you can also forgo the use of the coroutine
object and instead use a wrapper function. Such a wrapper function will resume
a particular coroutine when it is called and will return only the yielded
values. You can do this using `Library.coroutine.wrap()`:

```lua
-- A simple coroutine body that returns a value
local function task()
	return "done"
end

-- Create coroutine and return a wrapper function that resumes it
local f = coroutine.wrap(task)
-- Resume the coroutine as if we called coroutine.resume()
local result = f()
print(result) --> done
-- If an error occurs it will be raised here!
-- This differs from coroutine.resume() which acts similar to pcall()
```

The first value returned from `Library.coroutine.resume()` describes whether a
coroutine ran without errors. However, functions returned by
`Library.coroutine.wrap()` will not do this: instead they directly return the
values returned or passed to `Library.coroutine.yield()`, if any. Should an
error have occurred while running the coroutine function, the error is raised
on the call of the returned function.

### Producer Pattern Example

Imagine a task that produces repetitions of a word: each time it produces a
repetition, the next one will produce one more. For example, providing `Hello`
will produce `Hello`, `HelloHello`, `HelloHelloHello`, etc. To do this, you
can define `repeatThis()`:

```lua
-- This function repeats a word every time its coroutine is resumed
local function repeatThis(word)
	local repetition = ""
	while true do
		-- Do one repetition then yield the result
		repetition = repetition .. word
		coroutine.yield(repetition)
	end
end
```

To run this function as a coroutine, you can use `Library.coroutine.create()`
followed by multiple calls to `Library.coroutine.resume()`:

```lua
local function repeatThis(word)
	local repetition = ""
	while true do
		repetition = repetition .. word
		coroutine.yield(repetition)
	end
end

local repetitionCoro = coroutine.create(repeatThis)
print(coroutine.resume(repetitionCoro, "Hello"))  -- true, Hello
print(coroutine.resume(repetitionCoro))           -- true, HelloHello
print(coroutine.resume(repetitionCoro))           -- true, HelloHelloHello
```

For this producer function, you can also use `Library.coroutine.wrap()` to get
a function that produces values:

```lua
local function repeatThis(word)
	local repetition = ""
	while true do
		repetition = repetition .. word
		coroutine.yield(repetition)
	end
end

local f = coroutine.wrap(repeatThis)
print(f("Hello"))  -- Hello
print(f())         -- HelloHello
print(f())         -- HelloHelloHello
```


Closes and puts the provided coroutine in a dead state. This function
returns `true` unless the coroutine is in an error state, in which case it
returns `false` and the error message. A coroutine that is currently
running cannot be closed. A coroutine cannot be resumed after it is
closed.


coroutine.close

`true` unless the coroutine being closed is in an error state.


Closes and puts the provided coroutine in a dead state.


Creates a new coroutine with body `f`, which must be a Luau function, and
returns it as a `thread`. The returned coroutine starts in the `suspended`
state and does not begin executing until `Library.coroutine.resume()` is
called on it. The arguments passed to the first
`Library.coroutine.resume()` call are forwarded as the arguments to `f`.


coroutine.create

The Luau function to use as the coroutine body.


A new coroutine in the suspended state, ready to be resumed.


Creates a new coroutine, with body f. f must be a Luau function.


Registers `callback` on coroutine `co` that will be called when `co`
reaches a terminal state. The callback is called with a status string and
a set of values:

- `callback("finished", ...results)`. The coroutine function returned. All
  result values are forwarded to the callback.
- `callback("error", err)`. The coroutine terminated with an error. The
  error value is passed as the only additional argument.
- `callback("cancelled")`. `Library.coroutine.close()` or
  `Library.task.cancel()` was called on the coroutine. The coroutine did
  not complete its work. No extra values are provided.

Callbacks run at most once, in reverse registration order (LIFO).

When the coroutine reaches a terminal state during the invocation of
`Library.coroutine.resume()` or `Library.coroutine.close()`, those
functions will return only after callbacks complete their work. Callbacks
are invoked on the calling thread and may yield. If a callback errors,
remaining callbacks in the list are not invoked and `false` status with
the callback error is returned.

Attempting to register a callback on a dead coroutine raises an error.

If a coroutine reaches a terminal state in a resume through
`Library.coroutine.wrap()` closure and has callbacks registered, it raises
a "cannot run finalizers from a wrapped coroutine" error. A coroutine can
also reach the terminal state when it is being resumed by the engine or
closed with `Library.task.cancel()`; in this case, callbacks are executed
on a separate thread with errors reported as script errors.


coroutine.finally

callback

Function or a callable object to invoke.


Registers a callback to invoke when a coroutine finishes, errors, or is
closed.


Returns `true` if the coroutine this function is called within can safely
yield. Yielding a coroutine inside metamethods or C functions is
prohibited, with the exception of `pcall` and `xpcall`.


coroutine.isyieldable

Whether or not the coroutine can safely yield at this point.


Returns `true` if the coroutine this function is called within can safely
yield.


Starts or continues the execution of coroutine `co`. The first time you
resume a coroutine, it starts running its body. The values `...` are
passed as the arguments to the body function. If the coroutine has
yielded, resume restarts it; the values `...` are passed as the results
from the yield. If the coroutine runs without any errors, resume returns
true plus any values passed to yield (if the coroutine yields) or any
values returned by the body function (if the coroutine terminates). If
there is any error, resume returns false plus the error message.


coroutine.resume

Arguments passed to the coroutine body function (on first resume) or
returned from `coroutine.yield()` inside the coroutine (on subsequent
resumes).


`true` if the coroutine ran without errors, `false` if an error
occurred.


The values passed to `coroutine.yield()` or returned by the body
function on success, or the error message on failure.


Starts or continues the execution of coroutine `co`.


Returns the currently running coroutine as a `thread` value, or `nil` if
called from the main thread. The main thread is not considered a
coroutine, so only threads created by `Library.coroutine.create()` or
`Library.coroutine.wrap()` are returned by this function.


coroutine.running

The currently running coroutine, or `nil` if called from the main
thread.


Returns the status of coroutine co, as a string: 'running', if the
coroutine is running (that is, it called status); 'suspended', if the
coroutine is suspended in a call to yield, or if it has not started
running yet; 'normal' if the coroutine is active but not running (that is,
it has resumed another coroutine); and 'dead' if the coroutine has
finished its body function, or if it has stopped with an error.


coroutine.status

One of `"running"`, `"suspended"`, `"normal"`, or `"dead"`.


Returns the status of coroutine co as a string.


Creates a new coroutine, with body f. f must be a Luau function. Returns a
function that resumes the coroutine each time it is called. Any arguments
passed to the function behave as the extra arguments to resume. Returns
the same values returned by resume, except the first boolean. In case of
error, propagates the error.


coroutine.wrap

A wrapper function that resumes the coroutine each time it is called,
returning the yielded or returned values directly (without the boolean
status). Raises an error if the coroutine errors.


Creates a new coroutine and returns a function that, when called, resumes
the coroutine.


Suspends the execution of the calling coroutine. Any arguments to yield
are passed as extra results to resume. Yielding a coroutine inside
metamethods or C functions is prohibited, with the exception of `pcall`
and `xpcall`.


coroutine.yield

Values to return as additional results from the corresponding
`coroutine.resume()` call.


The arguments passed to the next `coroutine.resume()` call that
continues this coroutine.


coroutine

A function that executes alongside the main thread.


/reference/engine/libraries/coroutine.yaml

An object that runs connected functions upon a specific occurrence.

Data Type

RBXScriptSignal

Luau

Tuple

Variant

Data type having a value of either true or false.

boolean

Functions are blocks of code that can execute multiple times on command.

function

A sequence of characters, such as letters, numbers, and symbols.

string

A function that executes alongside the main thread.

Library

Experiences

Avatar

Assets

Samples and projects

Engine API

Open Cloud API

Studio

Analytics

Platform

Tutorials

Creator programs

Education

Learn

This method is asynchronous and returns an `Operation`, which represents the current state of the operation. It contains an endpoint path that you can poll to obtain the real response and applicable metadata. See the [documentation]({longRunningOperationsLink}) on long-running operations for more information.
            
The following sections describe the response and metadata objects that are provided when an operation completes.

Beta endpoints are ready for public use. Breaking changes are possible but rare.

These Open Cloud documentation pages will be removed on March 31, 2026. You will be automatically redirected to the new Open Cloud documentation at that time. {linkStart}Learn more{linkEnd}

These old Open Cloud pages will be removed and redirected on March 31, 2026. {linkStart}Learn more{linkEnd}

Experimental endpoints are ready for public use, but may experience breaking changes occasionally as the API contract is finalized.

This endpoint can be called in-experience through {httpServiceLinkStart}HttpService{httpServiceLinkEnd} with an API key.

This field may be set when creating a resource, but may not be modified by subsequent requests.

These fields may be set when creating a resource, but may not be modified by subsequent requests.

This field may be provided in requests, but will never be included in responses.

Legacy authentication method. Always prefer using API Key or OAuth 2.0 when available.

Per API Key: {maxInPeriod} requests every {periodInSeconds} seconds per IP Address

Requires no authentication to call. Typically has significantly lowered rate limits. Always prefer using API Key or OAuth 2.0 when available.

For each grouping, only one of the following fields in the schema has to be provided, the remaining can be excluded.

You can opt back in at any time. {linkStart}Provide feedback.{linkEnd}

You are viewing the old docs. {linkStart}Provide feedback.{linkEnd}

You can opt out at any time and be redirected back to the old reference pages. {linkStart}Provide feedback.{linkEnd}

You are viewing the revamped docs. {linkStart}Provide feedback.{linkEnd}

This field may be set on responses, but will be ignored in requests.

Note: Rate limits can be lower during high-traffic periods. Certain endpoints have additional rate limits. [Learn more about rate limits]({link}).

{limit} requests per day across all API keys for a user or group

{limit} requests per hour across all API keys for a user or group

{limit} requests per minute across all API keys for a user or group

{limit} requests per second across all API keys for a user or group

{limit} requests per minute per API key owner

{limit} request(s) per second per API key owner

Scopes control what permissions your credentials have. Your credentials can only access the endpoints supported by the scopes you selected.

Stable endpoints are production-ready and will almost never experience breaking changes during their lifetime.

This target enables you to limit your key's access to selected {requiredParts}

This target enables you to limit your key's access to selected {requiredParts} and {optionalParts}

Target types are used to restrict the resources that your credentials have permissions on. Only the selected resources can be acted on even if your account has permissions on additional resources. Some scopes do not have target parts. In these cases, all of your relevant resources can be acted on.

The universe Top Level Part does not need to be selected for user-owned API Keys. In this case, your API Key will have access to all of your user-owned experiences and group-owned experiences that you have the right group permissions on.

Try It Out is not yet supported for endpoints requiring API key or OAuth 2.0 authentication

Cookie authentication is disabled for high risk operations for safety.

Critical risk endpoints are extremely sensitive and Try It Out is disabled for safety

Note: Authentication headers are not included in this code sample. You may need to add an authentication header for this command to work.

This is a high risk endpoint that can modify or delete critical data. Use extreme caution when testing.

This API endpoint has been classified as HIGH RISK and may affect live data or user accounts.

Authenticated requests to high-risk APIs can make changes that cannot be undone. Please review your request parameters carefully before proceeding.

Please login to use cookie authentication

This is a low risk endpoint that retrieves data. This is generally safe to test.

This is a medium risk endpoint that modifies data. Test carefully with non-critical accounts, as changes may be permanent.

To keep your account safe, never paste text here from other sources or send information from this page to others.

You are about to test live API endpoints using your actual account credentials.

Only proceed if you understand the implications of the API calls you're about to make. Review the API documentation carefully before testing.

API calls will be made using your authenticated session

These are real API calls that may affect your account or data

Rate limits and other API restrictions apply

Some operations may modify or delete data

This endpoint has been superseded by these recommended alternative endpoints:

The following scopes are required to call this endpoint. For more
information on generating proper keys, see [Manage API keys]({apiKeyReferenceDocLink}).

For more information on generating keys, see [Manage API keys]({apiKeyReferenceDocLink}).

The following endpoints are available at paths relative to the base URL.

This string is formatted as a [FieldMask](/cloud/reference/types#fieldmask).

A JSON value can be `null`, `boolean`, `string`, `number`, `array`, or `object`.

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see [App registration and review]({oauth2ReferenceDocLink}).

For more information on how to register an OAuth 2.0 application, see [App registration and review]({oauth2ReferenceDocLink}).

The following objects describe payloads that are accepted or returned. See each individual endpoint for more information on when these objects are used.

The following scopes are required to call this endpoint.

Resource Paths

This string is formatted as a [Timestamp](/cloud/reference/types#timestamp).

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see [App Registration and Review]({oauth2ReferenceDocLink}).

Not Recommended

You are viewing the revamped Open Cloud reference.

You've opted out of the new Open Cloud reference.

Grants access to configure billing accounts and purchase ad credit.

View your ad campaigns and their performance.

Create, update, and manage your ad campaigns.

This allows viewing information about your assets.

This allows uploading and updating assets to Roblox.

This allows viewing asset permissions for subjects (including groups and experiences) and assets your account has access to.

This allows granting asset permissions to any subjects (including groups and experiences) and assets your account has access to.

This allows you to view the status and results of avatar auto-setup jobs on your behalf.

This allows you to create and manage avatar auto-setup jobs on your behalf.

Grants the ability to update badges owned by the user.

This allows viewing information about your commerce items.

This allows making changes to your synced commerce items.

This allows viewing information about your commerce merchant connections.

This allows editing of your commerce merchant connections.

This allows you to view information about your Creator Store products.

This allows you to modify information about your Creator Store products.

This allows you to view information about your Creator Store saves.

This allows you to modify information about your Creator Store saves.

Grants access to create data stores on your behalf.

Grants access to delete data stores on your behalf.

Grants access to read a list of data stores.

Grants access to take a snapshot of your data stores.

Grants access to create entries in your data stores.

Grants access to mark specified entries for deletion.

Grants access to list your data store's entries.

Grants access to read specified entries in your data stores.

Grants access to update the value, attributes, and users of an entry.

Grants access to delete revisions of your data store's entries.

Grants access to list revisions for your data store's entries.

Grants access to read revisions of your data store's entries.

Grants access to view configuration details for the authorized user's developer products.

Grants access to edit the authorized user's developer products.

This allows viewing information about your universe's environments.

This allows editing of your universe's environments.

Grants access to view configuration details for the authorized user's game passes.

Grants access to edit the authorized user's game passes.

Grants access to view community forums information for your account.

Grants access to manage community forums information for your account.

This allows viewing information about your communities.

This allows you to manage community join requests and role updates of lower-ranked community members for your account.

Allows you to view an instance's property data.

Allows you to modify the property data of instances (currently only supports Scripts).

This allows viewing information about your inventory.

Grants access to manage your badges and spend Robux.

Grants access to update the authorized user's badges.

Grants access to manage your developer products.

Grants access to read information about the experiences you have notifications on for.

Grants access to turn on or off notifications for experiences on your behalf.

Grants access to manage your communities.

Grants permission to read community information.

Grants access to read and write your localization tables

Grants access to manage team collaboration for all experiences you own.

Grants access to manage your experiences and certain information associated with your experiences (e.g. localization information).

Grants access to read your experiences' localization information.

Grants access to modify your experiences' localization preferences.

Grants access to manage your user account.

Grants access to modify user localization preferences.

Allows you to view the status, logs, and results of Luau execution tasks for the associated place.

Allows you to create new Luau execution tasks for the associated place.

Grants access to asynchronously flush all data structures in the universe.

Grants access to discard read items from the front of the queue.

Grants access to read items at the front of the queue.

Grants access to read your memory store items.

Grants access to create, update, and delete map items.

This grants the ability to publish messages on behalf of users.

This allows sending notifications from your experience to users.

(Deprecated) Grants access to read a list of entries in an ordered data store.

(Deprecated) Grants access to create a new entry in an ordered data store.

Grants access to list entries from an ordered data store.

Grants access to create entries in an ordered data store.

This allows listing secrets associated with your experience.

This allows creating and updating secrets associated with your experience.

This permission allows you to submit an evaluation job and view the job result.

Grants access to read about your subscription products.

This allows you to read thumbnail information on your behalf.

Grants the ability to read analytics alerts.

Grants the ability to create or modify analytics alerts.

Grants the ability to read game analytics.

Grants the ability to write resources related to game analytics.

Grants the ability to read place information.

Grants the ability to edit place information.

Grants access to publish new versions of experiences to Roblox.

This allows you to read thumbnails and thumbnail personalization settings for your experiences.

This allows you to upload and delete thumbnails and manage thumbnail personalization settings for your experiences.

Grants the ability to read experience information.

Grants access to edit the authorized user's experiences.

Allows you to view user restrictions in the experience.

Allows you to edit user restrictions in the experience.

This allows viewing notifications sent to your account.

Grants the ability to read the authorized user's premium and verified status.

This allows you to view the authorized user's social accounts.

Grants the ability to read a game's events.

This enables Single Sign-On functionality.

This grants access to read your profile information.

Summary