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

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.

• Features
• Installation
• Usage
• Contributing
• Support Me
• License

• Job Lifecycle Management: Track jobs through various statuses, including waiting, active, completed, and failed.
• Flexible Job Processors: Define custom logic for processing jobs using simple functions.
• Tooling: Gedis debugger tool can be used to assist development.
• Configurable Job Retention: Control how many completed and failed jobs are stored.
• Signals: Emit signals on job completion and failure.
• Pub/Sub Events: Subscribe to job lifecycle 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:

• added: When a new job is added to the queue.
• active: When a job is being processed.
• progress: When a job's progress is updated.
• completed: When a job has been completed successfully.
• failed: When a job has failed.

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)

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

• max_completed_jobs: The maximum number of completed jobs to keep. Set to 0 to delete jobs immediately after completion, or -1 to keep all completed jobs.
• max_failed_jobs: The maximum number of failed jobs to keep. Set to 0 to delete jobs immediately after failure, or -1 to keep all failed jobs.

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

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.

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)

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)

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.

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])

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

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.

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.

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

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