GedisQueue

image

A powerful and flexible job queue system for Godot, built on top of Gedis.

Documentation

Discord Mastodon Youtube GitHub Sponsors GitHub Stars

Stats

GedisQueue allows you to manage and process asynchronous jobs in your Godot projects, making it ideal for handling tasks like background processing, notifications, and more.

Table of Contents

Features

Pub/Sub Events

GedisQueue uses Gedis’s pub/sub functionality to broadcast events about the job lifecycle. You can subscribe to these events to monitor your queues in real-time.

The following events are published:

To subscribe to events, you can use the subscribe method on your Gedis instance:

signal psub_message(pattern, channel, message)

var gedis = Gedis.new()
var queue = GedisQueue.new()

func _ready():
    add_child(gedis)

    queue.setup(gedis)
    add_child(queue)

    gedis.psubscribe("gedis_queue:my_queue:events:*", self)
    pubsub_message.connect(_on_job_completed)

func _on_job_completed(pattern, channel, message):
    prints(pattern, channel, message)

Configuration

You can configure GedisQueue to control job retention and other settings.

var queue = GedisQueue.new()
queue.max_completed_jobs = 100 # Keep the last 100 completed jobs
queue.max_failed_jobs = 50    # Keep the last 50 failed jobs

Installation

To use GedisQueue, you need to have the Gedis addon installed and enabled in your Godot project. You can download Gedis from the Godot Asset Library or from its GitHub repository.

Once Gedis is set up, install the GedisQueue addon by copying the contents of the addons/GedisQueue directory into your project’s addons folder. Then, enable the “GedisQueue” plugin in your Project Settings.

Usage

Creating a Queue

To get started, you need to create an instance of the GedisQueue class. It’s recommended to add it to your scene tree as an autoloaded singleton for easy access throughout your project.

# In your main script or an autoloaded singleton
var queue = GedisQueue.new()

# Optionally pass your existing gedis instance
# queue.setup(my_gedis_instance)

add_child(queue)

Adding Jobs

You can add a job to a queue using the add method. Each job is identified by a unique ID and can carry any data you need. For example, you could add a job to grant a player a daily reward.

var job = queue.add("player_rewards", {
    "player_id": "player123",
    "reward_type": "daily_login_bonus",
    "items": ["gold_coins", "health_potion"],
    "quantity": [100, 2]
})

print("Reward job added with ID: ", job.id)

Processing Jobs

To process jobs, you need to define a worker that executes your custom logic. The process method takes a queue name and a processor function as arguments. This function will handle the logic for granting the reward.

var processor = func(job):
    var reward_data = job.data
    var player = get_player(reward_data.player_id)
    print("Granting reward to: ", player.name)
    
    for i in range(reward_data.items.size()):
        player.inventory.add_item(reward_data.items[i], reward_data.quantity[i])
        
    job.complete("Reward granted successfully")

var worker = queue.process("player_rewards", processor)

The processor function receives the job as an argument and is responsible for calling job.complete() or job.fail() to finish the job.

Job Lifecycle

You can monitor the status of jobs using the get_jobs method. This allows you to retrieve jobs in different states, such as waiting, active, completed, or failed. This is useful for tracking game events.

# Get all completed reward jobs
var completed_jobs = queue.get_jobs("player_rewards", [GedisQueue.STATUS_COMPLETED])
for job in completed_jobs:
    print("Job %s completed with result: %s" % [job.id, job.return_value])

# Get all failed jobs
var failed_jobs = queue.get_jobs("player_rewards", [GedisQueue.STATUS_FAILED])
for job in failed_jobs:
    print("Job %s failed with error: %s" % [job.id, job.failed_reason])

Batch Processing

GedisQueueWorker supports batch processing, allowing you to process multiple jobs concurrently. This can significantly improve performance when dealing with a large number of jobs.

The batch_size public variable on the GedisQueueWorker controls how many jobs are processed at once. The default value is 1, meaning jobs are processed one by one.

var worker = queue.process("player_rewards", processor)
worker.batch_size = 10 # Process up to 10 jobs at a time

Contributing

This addon is implemented in GDScript and does not require native compilation. To work on or test the addon, follow these steps:

  1. Clone the repository:

    git clone --recursive https://github.com/NodotProject/GedisQueue.git
cd GedisQueue

  2. Develop & Test:

    • The addon code lives under addons/GedisQueue. Copy that folder into your Godot project’s addons directory to test changes.
    • Run the project’s test suite with ./run_tests.sh.

  3. Contribute:

    Create a branch, make your changes, and open a pull request describing the work.

💖 Support Me

Hi! I’m krazyjakee 🎮, creator and maintain­er of the NodotProject - a suite of open‑source Godot tools (e.g. Nodot, Gedis etc) that empower game developers to build faster and maintain cleaner code.

I’m looking for sponsors to help sustain and grow the project: more dev time, better docs, more features, and deeper community support. Your support means more stable, polished tools used by indie makers and studios alike.

ko-fi

Every contribution helps maintain and improve this project. And encourage me to make more projects like this!

This is optional support. The tool remains free and open-source regardless.

Created with ❤️ for Godot Developers For contributions, please open issues on GitHub

License

GedisQueue is licensed under the MIT License. See the LICENSE file for more details.

This site is open source. Improve this page.