Using Caffeine

This guide will walk you through the basics of developing for Caffeine.

Assumptions

This guide assumes you have a rotation created. You can use your CR Quick Start guide if you don’t.

Foundations

To create a product on caffeine, you must send an HTTP request with a zip file (what we call a bundle.)

Every bundle must include a main.lua file. This file is how Caffeine determines where your files are, and how to load them. The main.lua file can be placed anywhere in your bundle, however we typically recommend placing it in your root directory.

File Structure

We’ll assume you’re using Caffeine local loading to develop your product, meaning you have caffeine installed, and your current file structure is:

├── scripts
│   ├── caffeine
│   │   ├── cx (key file)
│   │   ├── _loader.luac (loader file)
│   │   ├── scripts
│   │   │   ├── your_project_directory
│   │   │   │   ├── subdirectory
│   │   │   │   │   ├── something_else.lua
│   │   │   │   ├── main.lua
│   │   │   │   ├── rotation.lua

main.lua

Your main.lua file is how you determine which files should be loaded in which order. Here is the main.lua for our example:

local Unlocker, Caffeine, YourProject = ...

-- We load the dependencies first here, so lets assume something_else.lua has a dependency!
Caffeine:Require("@your_project_directory/subdirectory/something_else")

-- Now, let's load the actual rotation file!
Caffeine:Require("@your_project_directory/rotation")

Publishing Your Product

Bundling Your Files

Bundling can be a little finnicky sometimes. Lets make sure we get it done right.

When you have your Finder or File Explorer window open, don’t right-click on “your_project_directory” and compress to make the bundle. Instead, open “your_project_directory” up, highlight all of the files inside, and make a zip file out of those. That’s the bundle we will use to build our product.

Setting up CI/CD

In the Builds tab of your Project, you will see a CI/CD button when you click on one of your products.

This button will open a code window that has something similar to this:

name: Zip and Upload

on:
  push:
    branches:
      - main

jobs:
  zip-code:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Zipping Entire Repository
        run: |
          echo "Zipping the entire repository"
          zip -r bundle.zip .

      - name: Upload bundle.zip as artifact
        uses: actions/upload-artifact@v2
        with:
          name: bundle
          path: bundle.zip

  upload-zip:
    needs: zip-code
    runs-on: ubuntu-latest
    steps:
      - name: Download bundle.zip from artifact
        uses: actions/download-artifact@v2
        with:
          name: bundle

      - name: Upload ZIP to external server
        run: |
          echo "Uploading ZIP file"
          curl -F file=@bundle.zip https://caffeine.cx/api/projects/project-name/products/product-name/builds?buildKey=xxxx-xxxx

This is a GitHub Actions file. This is going to automate your deployment process.

Setting up GitHub Actions

Navigate to your GitHub repository and click “Actions” at the top. Click the link that says “set up a workflow yourself” near the top of the page.

Now, copy and paste the github action from your CI/CD button into the editor.

After saving, go to your repository settings, Actions, and enable your action to run after every push to your main branch. This will automatically deploy any changes you make to your main branch. It takes between 10 and 60 seconds for a deployment to be reflected on live.

Lets look at some more advanced examples.

Multi-product Repositories

If you have multiple products in your repository, it gets a bit more complex.

You will want to add additional steps to both the zip-code and upload-zip script. Let’s add an example file structure:

├── scripts
│   ├── caffeine
│   │   ├── cx (key file)
│   │   ├── _loader.luac (loader file)
│   │   ├── scripts
│   │   │   ├── your_project_directory
│   │   │   │   ├── mage
│   │   │   │   │   ├── mage.lua
│   │   │   │   ├── warrior
│   │   │   │   │   ├── warrior.lua
│   │   │   │   ├── main.lua

Now, we want to make it so each class only pushes to it’s respective product when it has been updated. To do that, we can utilize tags!

First, let’s add a mage-v0.1 tag to our main branch: git tag mage-v0.1 main.

Now, if we make some changes to our mage.lua file, and then git add and git commit those changes, we can push!

git push --atomic origin main mage-v0.1 will push your commit to the main branch with the tag mage-v0.1. You should increment your tag each time for easy tracking in the future.

Now, let’s build out our GitHub Action to search for tags and push a new build when needed!

name: Bundle and Upload

on:
    push:
        tags:
            - 'mage-v*'
            - 'warrior-v*'

jobs:
    handle-mage:
        if: startsWith(github.ref, 'refs/tags/mage-v')
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v2

          - name: Bundling mage...
            run: |
                zip -r your_mage.zip . -i your_project_directory/mage/*.lua

          - name: Uploading mage...
            run: |
                curl -F file=@your_mage.zip https://caffeine.cx/api/projects/ExampleProject/products/Mage/builds?buildKey=YourMageBuildKey

    handle-warrior:
        if: startsWith(github.ref, 'refs/tags/warrior-v')
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v2

          - name: Bundling warrior...
            run: |
                zip -r your_warrior.zip . -i your_project_directory/warrior/*.lua

          - name: Uploading warrior...
            run: |
                curl -F file=@your_warrior.zip https://caffeine.cx/api/projects/ExampleProject/products/Warrior/builds?buildKey=YourWarriorBuildKey

With this example, we are bundling each class individually, and then uploading them to their respective product.

Guides

Reference