We can say that this game was a form of steganography

“Steganography (from the Greek ‘hidden writing’) is the study and use of techniques to conceal the existence of a message within another, a form of security through obscurity. In other words, steganography is the particular branch of cryptology that consists of disguising one piece of writing within another in order to mask its true meaning.” - Wikipedia

Today I’m going to introduce another type of steganography — one that uses images to hide text inside pixels!

An image is composed of pixels, and each pixel represents the smallest possible color point using N bits. The more bits per color, the more colors a pixel can represent.

In my example I will focus only on 32-bit images (RGBA or ARGB) where 8 bits are used per color component. Obviously the technique is easily adaptable to other formats.

What happens if I change a single bit of the red component of every pixel? Even with the original image side by side, we would be unable to notice the difference — only a hashing algorithm like SHA1 could tell the files apart.

Therefore, I can use this same trick of altering pixels to hide a message inside the image, and only someone who knows the implementation will know how to extract the message.

But to do this we need to separate each bit of the message and change only one or two bits of each color component. It sounds like very little space, but if we do the math, an 800×600 image — which is considered low resolution today — can hold

800 width _ 600 height = 480000 pixels
480000 pixels _ 4 components = 1920000 bits
1920000 bits / 8 = 240000 bytes

In other words, we can fit a message of up to ~30 KB in an 800×600 image :)

Remember, we are talking about pixels, not file size — that depends on the chosen format. And speaking of format, this only works with lossless formats.

Implementation

To achieve our goal we need to master the ancient art of bit twiddling. There is an excellent resource on the subject called: Bit Twiddling Hacks

Writing a hidden message:

bool write(const QString& in, const QString& out, const QString& text){
  QImage image;
  if (!image.load(in))
      return false;

  QImage result = image.copy();
  int size = text.size();

  QByteArray bytes;
  bytes.reserve(size + headerSize);
  bytes += QString("%1").arg(size, headerSize, 10, QChar('0'));
  bytes += text.toLocal8Bit();

  QBitArray bits = byteArrayToBitarray(bytes);

  // Iterate over each pixel in the image
  for (int index = 0, y = 0; y < image.height(); ++y) {
    for (int x = 0; x < image.width(); ++x) {
      if (index >= bits.count())
        break;

      // Extract each color component individually
      QRgb pixel = image.pixel(x, y);
      int red   = qRed(pixel);
      int green = qGreen(pixel);
      int blue  = qBlue(pixel);
      int alpha = qAlpha(pixel);

      // For each component, take one bit from the message
      // and turn the last bit of the component on or off
      // to turn on:  component | (1 << 0x00)
      // to turn off: component & ~(1 << 0x00)
      red   = bits[index + 0] ? red   | (1 << 0x00) : red   & ~(1 << 0x00);
      green = bits[index + 1] ? green | (1 << 0x00) : green & ~(1 << 0x00);
      blue  = bits[index + 2] ? blue  | (1 << 0x00) : blue  & ~(1 << 0x00);
      alpha = bits[index + 3] ? alpha | (1 << 0x00) : alpha & ~(1 << 0x00);

      // Same thing for the second-to-last bit
      red   = bits[index + 4] ? red   | (1 << 0x01) : red   & ~(1 << 0x01);
      green = bits[index + 5] ? green | (1 << 0x01) : green & ~(1 << 0x01);
      blue  = bits[index + 6] ? blue  | (1 << 0x01) : blue  & ~(1 << 0x01);
      alpha = bits[index + 7] ? alpha | (1 << 0x01) : alpha & ~(1 << 0x01);

      // Write the pixel back to its original position
      result.setPixel(x, y, qRgba(red, green, blue, alpha));

      index += 8;
    }
  }

  return result.save(out);
}

Reading a hidden message from an image:

QByteArray read(const QString& filename) {
  QBitArray bits(8);
  QByteArray bytes;
  bytes.reserve(headerSize);
  int bytesToRead = 0;

  QImage image;
  if (image.load(filename)) {
    // Iterate over each pixel in the image
    for (int y = 0; y < image.height(); ++y) {
      for (int x = 0; x < image.width(); ++x) {
        uint32_t index = 0;
        QRgb pixel = image.pixel(x, y);

        // For each pixel, extract the last and second-to-last bit
        // of each color component
        bits[index++] = qRed(pixel)   & 1 << 0x00;
        bits[index++] = qGreen(pixel) & 1 << 0x00;
        bits[index++] = qBlue(pixel)  & 1 << 0x00;
        bits[index++] = qAlpha(pixel) & 1 << 0x00;

        bits[index++] = qRed(pixel)   & 1 << 0x01;
        bits[index++] = qGreen(pixel) & 1 << 0x01;
        bits[index++] = qBlue(pixel)  & 1 << 0x01;
        bits[index++] = qAlpha(pixel) & 1 << 0x01;

        // Convert the 8 bits into 1 byte and append to the bytes list
        bytes += bitArrayToByteArray(bits);

        // We need to know how many bytes to read;
        // for that, a header with this information
        // is inserted at the very beginning of the write process
        if (!bytesToRead && bytes.size() == headerSize) {
          bool ok;
          bytesToRead = bytes.toInt(&ok);
          if (!ok)
            return bytes;

          bytes.clear();
          bytes.reserve(bytesToRead);
        }

        // Read everything there was to read — return the bytes
        if (bytes.size() == bytesToRead) {
          return bytes;
        }
      }
    }
  }

  return bytes;
}

Proof

$ file gioconda.png
gioconda.png: PNG image data, 404 x 410, 8-bit/color RGBA, non-interlaced
$ ./stenog -i gioconda.png -o gioconda_stenog.png -m "flipping bits whilst updating pixels"
$ file gioconda_stenog.png
gioconda_stenog.png: PNG image data, 404 x 410, 8-bit/color RGBA, non-interlaced
$ ls -lah *.png
-rw-r--r--@ 1 Skhaz  staff   378K Apr  3 17:33 gioconda.png
-rw-r--r--  1 Skhaz  staff   394K Apr  3 17:46 gioconda_stenog.png
$ ./stenog -i gioconda_stenog.png
flipping bits whilst updating pixels

The file size changed slightly due to the format used — in this case, PNG.

This technique can be used to hide not only text, but also other images, sounds, or any kind of data.

Talk is cheap. Show me the code

The source code can be found in this gist

Since it’s a paid game, I need to provide proper bug support. With that in mind, and based on both professional and personal experience, I decided to use Sentry.

At first, integrating C++ and Lua should have been straightforward, but I ran into some issues when using the Conan package manager.

Initially, the package wasn’t being included in the compiler’s include flags, which led me to open an issue both on Conan Center and on Sentry Native.

After spending a whole day on this, I eventually found out that the fix was actually pretty simple. Now Carimbo has native support for Sentry, both on the web (WebAssembly) and natively (Android, iOS, Linux, Windows, and macOS).

Here’s how I managed to get it working.

CMake & Conan

This was certainly my biggest problem. For some reason, even when following Conan’s documentation, I couldn’t get it to include the header path for Sentry Native. In the end, my solution looked like this:

find_package(sentry CONFIG QUIET)

...

if(sentry_FOUND)
  target_link_libraries(${PROJECT_NAME} PRIVATE sentry-native::sentry-native)
  target_compile_definitions(${PROJECT_NAME} PRIVATE HAVE_SENTRY=1)
endif()

Web & Native at same time

The native part was pretty easy, but for the web part I had an insight while walking, because I realized I could inject JavaScript using the Emscripten API.

enginefactory& enginefactory::with_sentry(const std::string& dsn) noexcept {
  if (dsn.empty()) {
    return *this;
  }

  #ifdef EMSCRIPTEN
    const auto script = std::format(
      R"javascript(
        (function(){{
          const __dsn="{}";
          if (window.Sentry && window.__sentry_inited__) return;
          const script = document.createElement('script');
          script.src = 'https://cdn.jsdelivr.net/npm/@sentry/browser@latest/build/bundle.min.js';
          script.crossOrigin = 'anonymous';
          script.defer = true;
          script.onload = function(){{
            if (!window.Sentry) return;
            window.Sentry.init({{ dsn: __dsn }});
            window.__sentry_inited__ = true;
          }};
          document.head.appendChild(script);
        }})();
      )javascript",
      dsn
    );

    emscripten_run_script(script.c_str());
  #endif

  #if defined(HAVE_SENTRY) && !defined(SANDBOX)
    auto *options = sentry_options_new();
    sentry_options_set_dsn(options, dsn.c_str());
    // sentry_options_set_debug(options, 1);
    // sentry_options_set_logger_level(options, SENTRY_LEVEL_DEBUG);
    sentry_init(options);
  #endif

  return *this;
}

Better Lua Stack Traces

Since the game assets are stored in a compressed file, PhysicsFS provides an API to handle them transparently. It’s great for distributing the game — you only need the cartridge.zip and the executable — and it works even better on the web. The engine must provide a searcher so that Lua can find the game’s other Lua scripts. For this, I use a custom searcher: it first looks for the scripts inside the game package, and if they’re not found, it falls back to the interpreter’s default search to load them from the standard library.

sol::object searcher(sol::this_state state, const std::string& module) {
  sol::state_view lua{state};

  const auto filename = std::format("scripts/{}.lua", module);
  const auto buffer = storage::io::read(filename);
  std::string_view script{reinterpret_cast<const char *>(buffer.data()), buffer.size()};

  const auto loader = lua.load(script, std::format("@{}", filename));
  if (!loader.valid()) [[unlikely]] {
    sol::error err = loader;
    throw std::runtime_error(err.what());
  }

  return sol::make_object(lua, loader.get<sol::protected_function>());
}

lua["searcher"] = &searcher;

const auto inject = std::format(R"lua(
  local list = package.searchers or package.loaders
  table.insert(list, searcher)
)lua");

lua.script(inject);

To improve stack traces, the secret lies in the second parameter of lua.load. You can pass a string starting with @ followed by the file name.

This alone gives you a much richer stack trace.

Error handling

In Carimbo, I have a terminate hook that catches any exception and atexit hooks to always handle cleanup.

[[noreturn]] void fail() {
  if (const auto ptr = std::current_exception()) {
    const char* error = nullptr;

    try {
      std::rethrow_exception(ptr);
    } catch (const std::bad_exception&) {
    } catch (const std::exception& e) {
      error = e.what();
    } catch (...) {
      error = "Unhandled unknown exception";
    }

    if (error) {
      #ifdef HAVE_SENTRY
        const auto exc = sentry_value_new_exception("exception", error);
        const auto ev = sentry_value_new_event();

        sentry_event_add_exception(ev, exc);

        sentry_capture_event(ev);
      #endif

      #ifdef HAVE_STACKTRACE
        boost::stacktrace::stacktrace st;
        std::println(stderr, "Stack trace:\n{}\n", boost::stacktrace::to_string(st));
      #endif

      std::println(stderr, "{}", error);

      SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "Ink Spill Disaster", error, nullptr);

      #ifdef DEBUG
        #ifdef _MSC_VER
          __debugbreak();
        #else
          raise(SIGTRAP);
        #endif
      #endif
    }
  }

  std::exit(EXIT_FAILURE);
}

application::application(int argc, char **argv) {
  UNUSED(argc);
  UNUSED(argv);

  std::set_terminate(fail);

  constexpr const auto fn = [](int) {
    std::exit(EXIT_SUCCESS);
  };

  std::signal(SIGINT, fn);
  std::signal(SIGTERM, fn);

  #ifdef HAVE_SENTRY
    std::atexit([] { sentry_close(); });
  #endif

  std::atexit([] { PHYSFS_deinit(); });
  std::atexit([] { SDL_Quit(); });

  SDL_Init(SDL_INIT_GAMEPAD | SDL_INIT_VIDEO);
  PHYSFS_init(argv[0]);
  #ifdef HAVE_STEAM
    SteamAPI_InitSafe();
  #endif
}

int32_t application::run() {
  static_assert(std::endian::native == std::endian::little);

  const auto* p = std::getenv("CARTRIDGE");

  storage::filesystem::mount(p ? p : "cartridge.zip", "/");

  auto se = scriptengine();
  se.run();

  return 0;
}

Conclusion

This way, I can provide Sentry support in a practically universal and abstract manner for the engine’s user.

You can find more details about the engine and its implementation in the official repository: github.com/willtobyte/carimbo.

You can find more details here: v8/src/numbers/math-random.cc at main · v8/v8

I’m currently working on a game that uses random in the main loop, which is quite slow. So to work around that, I implemented a pseudo-random function.

local seed = os.time()
local function random()
  seed = (1103515245 * seed + 12345) % 2147483648
  return seed
end

This is a Linear Congruential Generator (LCG) — one of the oldest and simplest methods for generating pseudorandom numbers. For the noise effect, I end up calling random up to 6 times per loop, which is extremely costly, and not even the C++ implementation of xorshift128+ below could save me.

Anyway, I ended up replacing Lua’s implementation with the one below, because optimizations are always welcome — especially when the gain in randomness is significantly higher.

static std::array<uint64_t, 2> prng_state;

void seed(uint64_t value) {
  constexpr uint64_t mix = 0xdeadbeefcafebabeULL;
  if (value == 0) value = 1;
  prng_state[0] = value;
  prng_state[1] = value ^ mix;
}

uint64_t xorshift128plus() {
  const auto s1 = prng_state[0];
  const auto s0 = prng_state[1];
  const auto result = s0 + s1;

  prng_state[0] = s0;
  prng_state[1] = (s1 ^ (s1 << 23)) ^ s0 ^ ((s1 ^ (s1 << 23)) >> 18) ^ (s0 >> 5);

  return result;
}

double xorshift_random_double() {
  static constexpr const auto inv_max = 1.0 / static_cast<double>(std::numeric_limits<uint64_t>::max());

  return static_cast<double>(xorshift128plus()) * inv_max;
}

lua_Integer xorshift_random_int(const lua_Integer low, const lua_Integer high) {
  const auto ulow = static_cast<uint64_t>(low);
  const auto range = static_cast<uint64_t>(high - low + 1);
  return static_cast<lua_Integer>(ulow + (xorshift128plus() % range));
}

const auto now = std::chrono::high_resolution_clock::now().time_since_epoch().count();
seed(static_cast<uint64_t>(now));

lua["math"]["random"] = sol::overload(
  []() -> double {
    return xorshift_random_double();
  },
  [](lua_Integer upper) -> lua_Integer {
    return xorshift_random_int(1, upper);
  },
  [](lua_Integer lower, lua_Integer upper) -> lua_Integer {
    return xorshift_random_int(lower, upper);
  }
);

lua["math"]["randomseed"] = [](lua_Integer seed_value) {
  seed(static_cast<uint64_t>(seed_value));
};

Spoiler: it’s not shaders

I’m waiting for a universal solution that the SDL developers are working on — cross-platform, multi-API shaders, the SDL_shadercross. The idea is that you write shaders in a single language, and at runtime, they get compiled for the target GPU. Unfortunately, it’s a large and complex project, and it will take time before it becomes stable.

In the meantime, in my Carimbo engine, I was wondering if I could implement something similar to shaders — something that would allow Lua code to write arbitrary pixels into a buffer and stream that buffer into a texture.

So I created what I call a canvas, which is basically a texture the same size as the screen, rendered after certain elements.

canvas::canvas(std::shared_ptr<renderer> renderer)
    : _renderer(std::move(renderer)) {
  int32_t lw, lh;
  SDL_RendererLogicalPresentation mode;
  SDL_GetRenderLogicalPresentation(*_renderer, &lw, &lh, &mode);

  float_t sx, sy;
  SDL_GetRenderScale(*_renderer, &sx, &sy);

  const auto width = static_cast<int32_t>(std::lround(static_cast<float>(lw) / sx));
  const auto height = static_cast<int32_t>(std::lround(static_cast<float>(lh) / sy));

  SDL_Texture *texture = SDL_CreateTexture(*_renderer, SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STREAMING, width, height);
  if (!texture) [[unlikely]] {
    throw std::runtime_error(std::format("[SDL_CreateTexture] {}", SDL_GetError()));
  }

  SDL_SetTextureBlendMode(texture, SDL_BLENDMODE_BLEND);

  _framebuffer.reset(texture);
}

void canvas::set_pixels(const uint32_t* pixels) noexcept {
  const auto ptr = _framebuffer.get();
  const auto pitch = static_cast<int>(static_cast<size_t>(ptr->w) * sizeof(uint32_t));

  SDL_UpdateTexture(ptr, nullptr, pixels, pitch);
}

The set_pixel function receives a pointer to a uint32_t buffer that exactly matches the texture size. This pointer is actually a Lua string, which I found to be the most performant way to transfer data between Lua and C++ without relying on preallocated buffers.

This way:

lua.new_usertype<graphics::canvas>(
  "Canvas",
  sol::no_constructor,
  "pixels", sol::property(
    [](const graphics::canvas&) {
      return nullptr;
    },
    [](graphics::canvas& canvas, const char* data) {
      canvas.set_pixels(reinterpret_cast<const uint32_t*>(data));
    }
  )
);

On Lua side:

function Effect:new(width, height)
  local w, h = width or 480, height or 270
  local canvas = engine:canvas()
  local self = setmetatable({
    canvas = canvas,
    w = w,
    h = h,
  }, Effect)

  return self
end

function Effect:loop()
  -- Some cool effect...
  self.canvas.pixels = rep(char(0, 0, 0, 220), self.w * self.h)`
end

Some effects I’ve created so far:

https://youtu.be/GUWTWRQuzxw

https://youtu.be/usJ9QM7V8BI

https://youtu.be/DUhQmL91cNA

Since I was in a rush and a bit lazy—because I can’t afford to spend too much time on personal projects—I decided to use AI to optimize it, and this was the best solution I could squeeze out. It went from 40 FPS down to 17, much worse than the initial implementation!

AI Code:

[](graphics::canvas& canvas, sol::table table) {
  const auto n = table.size();
  static std::vector<uint32_t> buffer;

  if (buffer.size() != n) [[unlikely]] {
    buffer.resize(n);
  }

  const auto L = table.lua_state();

  table.push();
  const int table_idx = lua_gettop(L);

  uint32_t* const data = buffer.data();

  constexpr std::size_t batch_size = 8;
  const std::size_t full_batches = n / batch_size;

  for (std::size_t batch = 0; batch < full_batches; ++batch) {
    const std::size_t start_idx = batch * batch_size;

    for (std::size_t j = 0; j < batch_size; ++j) {
      lua_rawgeti(L, table_idx, static_cast<int>(start_idx + j + 1));
    }

    for (std::size_t j = batch_size; j > 0; --j) {
      data[start_idx + j - 1] = static_cast<uint32_t>(lua_tointeger(L, -1));
      lua_pop(L, 1);
    }
  }

  const std::size_t remaining_start = full_batches * batch_size;
  for (std::size_t i = remaining_start; i < n; ++i) {
    lua_rawgeti(L, table_idx, static_cast<int>(i + 1));
    data[i] = static_cast<uint32_t>(lua_tointeger(L, -1));
    lua_pop(L, 1);
  }

  lua_pop(L, 1);
  canvas.set_pixels(buffer);
}

Naturally, the code was not just complex, but also way slower.

That’s when I decided to take my brain off the shelf and came up with this solution:

[](graphics::canvas& canvas, const char* data) {
  canvas.set_pixels(reinterpret_cast<const uint32_t*>(data));
}

Kabum! Smooth 60 frames per second, even at 8K resolution or higher.

If you’ve been following me, you know I’ve been working in my free time on a 2D game engine where creators can build games using only Lua — and I’d say, even fairly complex ones.

Right now, I’m working on a point-and-click game that you can play here: https://bereprobate.com/. It’s built using this same engine, and I’m publishing builds in parallel to Steam and the Web using GitHub Actions.

The thing is, Steam — which is the main target platform for this game — supports achievements, and I want to include them. But to use achievements, you have to link the Steam library to your engine. The problem is, doing that creates a dependency on that library in the binaries, which I don’t want. I also don’t want to maintain a separate build just for that.

Then I thought: “Why not load the Steam library dynamically? Use LoadLibraryA on Windows and dlopen on macOS. (Sorry Linux — it’s Proton-only for now.)”

I tried the experiment below, and it worked. If the DLL/dylib is present, the Steam features work just fine. If not, everything runs normally.

#include "steam.hpp"

#if defined(_WIN32)
  #include <windows.h>
  #define DYNLIB_HANDLE HMODULE
  #define DYNLIB_LOAD(name) LoadLibraryA(name)
  #define DYNLIB_SYM(lib, name) GetProcAddress(lib, name)
  #define STEAM_LIB_NAME "steam_api64.dll"
#elif defined(__APPLE__)
  #include <dlfcn.h>
  #define DYNLIB_HANDLE void*
  #define DYNLIB_LOAD(name) dlopen(name, RTLD_LAZY)
  #define DYNLIB_SYM(lib, name) dlsym(lib, name)
  #define STEAM_LIB_NAME "libsteam_api.dylib"
#endif

#ifndef S_CALLTYPE
  #define S_CALLTYPE __cdecl
#endif

#if defined(DYNLIB_LOAD)

using SteamAPI_InitSafe_t     = bool(S_CALLTYPE *)();
using SteamAPI_Shutdown_t     = void(S_CALLTYPE *)();
using SteamAPI_RunCallbacks_t = void(S_CALLTYPE *)();
using SteamUserStats_t        = void*(S_CALLTYPE *)();
using GetAchievement_t        = bool(S_CALLTYPE *)(void*, const char*, bool*);
using SetAchievement_t        = bool(S_CALLTYPE *)(void*, const char*);
using StoreStats_t            = bool(S_CALLTYPE *)(void*);

static DYNLIB_HANDLE hSteamApi = DYNLIB_LOAD(STEAM_LIB_NAME);

#define LOAD_SYMBOL(name, sym) reinterpret_cast<name>(reinterpret_cast<void*>(DYNLIB_SYM(hSteamApi, sym)))

static const auto pSteamAPI_InitSafe     = LOAD_SYMBOL(SteamAPI_InitSafe_t, "SteamAPI_InitSafe");
static const auto pSteamAPI_Shutdown     = LOAD_SYMBOL(SteamAPI_Shutdown_t, "SteamAPI_Shutdown");
static const auto pSteamAPI_RunCallbacks = LOAD_SYMBOL(SteamAPI_RunCallbacks_t, "SteamAPI_RunCallbacks");
static const auto pSteamUserStats        = LOAD_SYMBOL(SteamUserStats_t, "SteamAPI_SteamUserStats_v013");
static const auto pGetAchievement        = LOAD_SYMBOL(GetAchievement_t, "SteamAPI_ISteamUserStats_GetAchievement");
static const auto pSetAchievement        = LOAD_SYMBOL(SetAchievement_t, "SteamAPI_ISteamUserStats_SetAchievement");
static const auto pStoreStats            = LOAD_SYMBOL(StoreStats_t, "SteamAPI_ISteamUserStats_StoreStats");

bool SteamAPI_InitSafe() {
  return pSteamAPI_InitSafe ? pSteamAPI_InitSafe() : false;
}

void SteamAPI_Shutdown() {
  pSteamAPI_Shutdown ? pSteamAPI_Shutdown() : void();
}

void SteamAPI_RunCallbacks() {
  pSteamAPI_RunCallbacks ? pSteamAPI_RunCallbacks() : void();
}

void* SteamUserStats() {
  return pSteamUserStats ? pSteamUserStats() : nullptr;
}

bool GetAchievement(const char* name) {
  bool achieved = false;
  return pGetAchievement ? (pGetAchievement(SteamUserStats(), name, &achieved) && achieved) : false;
}

bool SetAchievement(const char* name) {
  return pSetAchievement ? pSetAchievement(SteamUserStats(), name) : false;
}

bool StoreStats() {
  return pStoreStats ? pStoreStats(SteamUserStats()) : false;
}

#else

bool SteamAPI_InitSafe()            { return false; }
void SteamAPI_Shutdown()           {}
void SteamAPI_RunCallbacks()       {}
void* SteamUserStats()             { return nullptr; }
bool GetAchievement(const char*)   { return false; }
bool SetAchievement(const char*)   { return false; }
bool StoreStats()                  { return false; }

#endif

Achivement class

void achievement::unlock(std::string id) {
  if (!SteamUserStats()) {
    return;
  }

  const auto* ptr = id.c_str();

  if (GetAchievement(ptr)) {
    return;
  }

  SetAchievement(ptr);
  StoreStats();
}

Binding

steam::achievement achievement;

lua.new_usertype<steam::achievement>(
  "Achievement",
  "unlock", &steam::achievement::unlock
);

lua["achievement"] = &achievement;

Usage

achievement:unlock("NEW_ACHIEVEMENT_1_3")

Do you work from home, and do people in your household always show up at the worst possible moments?

Let me introduce the “I’m in Meeting” IoT device: it lights up at your office door whenever you turn on your webcam.

It consists of an ESP32 with mDNS connected to Wi-Fi, using the Arduino framework for simplicity. The ESP32 exposes an HTTP server that handles a PATCH request on the /camera endpoint. This endpoint receives a JSON payload with a status of “on” or “off”, and turns the LED panel red or blue accordingly.

For those who don’t know, mDNS (or Bonjour on Apple platforms) is a way to assign an IP address to a .local hostname for the device, so I don’t need to figure out its IP manually—just use the local domain.

Super convenient, right?

On the other side, I have a Python daemon that periodically queries Apple’s API to check if any cameras are in use, and then sends a PATCH request with “on” or “off” to http://esp32.local/camera.

Very simple, but quite useful.

See in action here https://youtu.be/c-cD_JLuCuQ

Source code https://github.com/skhaz/onair

See you!

In my free time, I’m working on a 2D hide-and-seek game, and as you might expect, I’ve automated the entire release pipeline for publishing on Steam. After a few attempts, when it finally worked, it felt like magic: all I had to do was create a new tag, and within minutes, the Steam client was downloading the update.

As I mentioned earlier, I have a 2D engine that, while simple, is quite comprehensive. With each new tag, I compile it in parallel for Windows, macOS, Linux, and WebAssembly. Once compilation is complete, I create a release and publish it on GitHub. Releases · willtobyte/carimbo

This way

name: Release

on:
  push:
    tags:
      - "v*.*.*"

jobs:
  release:
    runs-on: ${{ matrix.config.os }}

    permissions:
      contents: write

    strategy:
      fail-fast: true

      matrix:
        config:
          - name: macOS
            os: macos-latest
          - name: Ubuntu
            os: ubuntu-latest
          - name: WebAssembly
            os: ubuntu-latest
          - name: Windows
            os: windows-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Cache Dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.conan2/p
            C:/Users/runneradmin/.conan2/p
          key: ${{ matrix.config.name }}-${{ hashFiles('**/conanfile.py') }}
          restore-keys: |
            ${{ matrix.config.name }}-

      - name: Prepare Build Directory
        run: mkdir build

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Conan
        run: pip install conan

      - name: Detect Conan Profile
        run: conan profile detect --force

      - name: Set Conan Center
        run: conan remote update conancenter --url https://center2.conan.io

      - name: Detect WebAssembly Conan Profile
        if: matrix.config.name == 'WebAssembly'
        run: |
          cat > ~/.conan2/profiles/webassembly <<EOF
          include(default)

          [settings]
          arch=wasm
          os=Emscripten

          [tool_requires]
          *: emsdk/3.1.73
          EOF

      - name: Install Windows Or macOS Dependencies
        if: matrix.config.name == 'Windows' || matrix.config.name == 'macOS'
        run: conan install . --output-folder=build --build=missing --settings compiler.cppstd=20 --settings build_type=Release

      - name: Install Ubuntu Dependencies
        if: matrix.config.name == 'Ubuntu'
        run: conan install . --output-folder=build --build=missing --settings compiler.cppstd=20 --settings build_type=Release --conf "tools.system.package_manager:mode=install" --conf "tools.system.package_manager:sudo=True"

      - name: Install WebAssembly Dependencies
        if: matrix.config.name == 'WebAssembly'
        run: conan install . --output-folder=build --build=missing --profile=webassembly --settings compiler.cppstd=20 --settings build_type=Release

      - name: Configure
        run: cmake .. -DCMAKE_TOOLCHAIN_FILE="conan_toolchain.cmake" -DCMAKE_BUILD_TYPE=Release
        working-directory: build

      - name: Build
        run: cmake --build . --parallel 8 --config Release --verbose
        working-directory: build

      - name: Create Artifacts Directory
        run: mkdir artifacts

      - name: Compress Artifacts
        if: matrix.config.name == 'macOS'
        working-directory: build
        run: |
          chmod -R a+rwx carimbo
          tar -cpzvf macOS.tar.gz carimbo
          mv macOS.tar.gz ../artifacts

      - name: Compress Artifacts
        if: matrix.config.name == 'Ubuntu'
        working-directory: build
        run: |
          chmod +x carimbo
          tar -czvf Ubuntu.tar.gz --mode='a+rwx' carimbo
          mv Ubuntu.tar.gz ../artifacts

      - name: Compress Artifacts
        if: matrix.config.name == 'WebAssembly'
        working-directory: build
        run: |
          zip -jr WebAssembly.zip carimbo.wasm carimbo.js
          mv WebAssembly.zip ../artifacts

      - name: Compress Artifacts
        if: matrix.config.name == 'Windows'
        working-directory: build
        shell: powershell
        run: |
          Compress-Archive -LiteralPath 'Release/carimbo.exe' -DestinationPath "../artifacts/Windows.zip"

      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          tag_name: ${{ github.event.inputs.tagName }}
          prerelease: ${{ github.events.inputs.prerelease }}
          files: artifacts/*

Publishing on Steam is quite simple. First, you need a developer account with the correct documentation and fees paid.

After that, you’ll need to generate some secret keys as follows:

steamcmd +login <username> <password> +quit

If you don’t have the steamcmd application installed, you’ll need to install it using:

cast install --cask steamcmd

Copy the contents of the authentication file:

cat ~/Library/Application\ Support/Steam/config/config.vdf | base64 | pbcopy

Note: You must have MFA enabled. After logging in, run the command below and copy the output into a GitHub Action variable named STEAM_CONFIG_VDF.

Also, create the variables STEAM_USERNAME with your username and STEAM_APP_ID with your game’s ID.

Additionally, the Action downloads the latest Carimbo release for Windows only (sorry Linux and macOS users, my time is limited). Ideally, I should pin the runtime version (the Carimbo version) using something like a runtime.txt file. Maybe I’ll implement this in the future, but for now, everything runs on the bleeding edge. :-)

on:
  push:
    tags:
      - "v*.*.*"

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      CARIMBO_TAG: "v1.0.65"

    permissions:
      contents: write

    steps:
      - name: Clone the repository
        uses: actions/checkout@v4

      - name: Install 7zip
        run: sudo apt install p7zip-full

      - name: Create bundle
        run: 7z a -xr'!.git/*' -xr'!.git' -xr'!.*' -t7z -m0=lzma -mx=6 -mfb=64 -md=32m -ms=on bundle.7z .

      - name: Download Carimbo runtime
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release download ${{ env.CARIMBO_TAG }} --repo willtobyte/carimbo --pattern "Windows.zip"

      - name: Extract Carimbo runtime
        run: 7z x Windows.zip -o.

      - name: Copy files
        run: |
          mkdir -p output
          mv bundle.7z output/
          mv carimbo.exe output/

      - name: Upload build to Steam
        uses: game-ci/steam-deploy@v3
        with:
          username: ${{ secrets.STEAM_USERNAME }}
          configVdf: ${{ secrets.STEAM_CONFIG_VDF }}
          appId: ${{ secrets.STEAM_APP_ID }}
          rootPath: output
          depot1Path: "."
          releaseBranch: prerelease

Boom! If everything is correct, your game should appear in your Steam client under the list of owned games.

TL;DR

After a while, I decided to resume work on my game engine.

I made a game for my son. I could have used an existing engine, but I chose to write everything from scratch because code is like pasta—it’s much better and more enjoyable when homemade.

This actually reminds me of when my father used to build my toys, from kites to wooden slides. Good memories. I have decided to do the same using what I know: programming.

You can watch it here or play it here, (runs in the browser thanks to WebAssembly), use A and D for moving around and space to shoot.

The engine was written in C++17, and the games are in Lua. The engine exposes some primitives to the Lua VM, which in turn coordinates the entire game.

Game source code and engine source code.

Artwork by Aline Cardoso @yuugenpixie.

Result

Going Deep

The entire game is scripted in Lua.

First, we create the engine itself.

local engine = EngineFactory.new()
    :set_title("Mega Rick")
    :set_width(1920)
    :set_height(1080)
    :set_fullscreen(false)
    :create()

Then we point to some resources for asset prefetching; they are loaded lazily to avoid impacting the game loop.

engine:prefetch({
  "blobs/bomb1.ogg",
  "blobs/bomb2.ogg",
  "blobs/bullet.png",
  "blobs/candle.png",
  "blobs/explosion.png",
  "blobs/octopus.png",
  "blobs/player.png",
  "blobs/princess.png",
  "blobs/ship.png"
})

We created the postal service, which is something I borrowed from languages like Erlang, where an entity can send messages to any other. As we’ll see below, the bullet sends a hit message when it collides with the octopus, and the octopus, upon receiving the hit, decrements its own health.

We also obtain the SoundManager to play sounds and spawn the main entities.

local postal = PostalService.new()
local soundmanager = engine:soundmanager()
local octopus = engine:spawn("octopus")
local player = engine:spawn("player")
local princess = engine:spawn("princess")
local candle1 = engine:spawn("candle")
local candle2 = engine:spawn("candle")

It’s not a triple-A title, but I’m very careful with resource management. A widely known technique is to create an object pool that you can reuse. In the code below, we limit it to a maximum of 3 bullets present on the screen.

The on_update method is a callback called each loop in the engine. In the case of the bullet, I check if it has approached the green octopus. If so, I send a message to it indicating that it received a hit.

for _ = 1, 3 do
    local bullet = entitymanager:spawn("bullet")
    bullet.placement:set(-128, -128)
    bullet:on_collision("octopus", function(self)
      self.action:unset()
      self.placement:set(-128, -128)
      postalservice:post(Mail.new(octopus, "bullet", "hit"))
      table.insert(bullet_pool, self)
    end)
    table.insert(bullet_pool, bullet)
  end

On the octopus’s side, when it receives a “hit” message, the entity triggers an explosion animation, switches to attack mode, and decreases its health by 1. If it reaches 0, it changes the animation to “dead”.

octopus = entitymanager:spawn("octopus")
octopus.kv:set("life", 16)
octopus.placement:set(1200, 622)
octopus.action:set("idle")
octopus:on_mail(function(self, message)
  local behavior = behaviors[message]
  if behavior then
    behavior(self)
  end
end)
octopus.kv:subscribe("life", function(value)
  vitality:set(string.format("%02d-", math.max(value, 0)))

  if value <= 0 then
    octopus.action:set("dead")
    if not timer then
      timemanager:singleshot(3000, function()
        local function destroy(pool)
          for i = #pool, 1, -1 do
            entitymanager:destroy(pool[i])
            table.remove(pool, i)
            pool[i] = nil
          end
        end

        destroy(bullet_pool)
        destroy(explosion_pool)
        destroy(jet_pool)

        entitymanager:destroy(octopus)
        octopus = nil

        entitymanager:destroy(player)
        player = nil

        entitymanager:destroy(princess)
        princess = nil

        entitymanager:destroy(candle1)
        candle1 = nil

        entitymanager:destroy(candle2)
        candle2 = nil

        entitymanager:destroy(floor)
        floor = nil

        overlay:destroy(vitality)
        vitality = nil

        overlay:destroy(online)
        online = nil

        scenemanager:set("gameover")

        collectgarbage("collect")

        resourcemanager:flush()
      end)
      timer = true
    end
  end
end)
octopus:on_animationfinished(function(self)
  self.action:set("idle")
end)

And finally, the player’s on_update, where I apply the velocity if any movement keys are pressed, or set the animation to idle if none are pressed.

We also have the projectile firing, where the fire function is called, taking an instance of a bullet from the pool, placing it in a semi-random position, and applying velocity.

function loop()
  if not player then
    return
  end

  player.velocity.x = 0

  if statemanager:is_keydown(KeyEvent.left) then
    player.reflection:set(Reflection.horizontal)
    player.velocity.x = -360
  elseif statemanager:is_keydown(KeyEvent.right) then
    player.reflection:unset()
    player.velocity.x = 360
  end

  player.action:set(player.velocity.x ~= 0 and "run" or "idle")

  if statemanager:is_keydown(KeyEvent.space) then
    if not key_states[KeyEvent.space] then
      key_states[KeyEvent.space] = true

      -- player.velocity.y = -360

      if octopus.kv:get("life") <= 0 then
        return
      end

      if #bullet_pool > 0 then
        local bullet = table.remove(bullet_pool)
        local x = (player.x + player.size.width) + 100
        local y = player.y + 10
        local offset_y = (math.random(-2, 2)) * 30

        bullet.placement:set(x, y + offset_y)
        bullet.action:set("default")
        bullet.velocity.x = 800

        local sound = "bomb" .. math.random(1, 2)
        soundmanager:play(sound)
      end
    end
  else
    key_states[KeyEvent.space] = false
  end
end

In The End

In the end, he requested some minor tweaks, such as the projectile being the princess sprite, the target being the player, and the entity that shoots being the green octopus. 🤷‍♂️

Since the first URL shorteners emerged, that’s always drawn me in for some reason, perhaps because I figured out on my own that they encoded the primary key in base36 (maybe).

So around ~2010, I decided to make my own. It was called “encurta.ae” (make it short there in Portuguese), and it was based on AppEngine. Even back then, I was quite fond of serverless and such.

It worked great locally, but when I deployed it, the datastore IDs were too large, causing the URLs to be too long.

Fast-forward to nowadays, I’ve decided to bring this project to life again. This time with a twist: when shortening the URL, the shortener would take a screenshot of the website and embed Open Graph tags in the redirect URL. This way, when shared on a social network, the link would display a title, description, and thumbnail that accurately represent what the user is about to open.

Stack

Typically, I use serverless for my personal projects because they scale to zero, thus eliminating costs when not in use. However, after working with serverless for many years, I’ve been wanting to experiment with a more grounded and down-to-earth approach to development and deployment.

• I opted to use Go, with several goroutines performing tasks in parallel, and a purely written work queue mechanism.
• Playwright & Chromium for automation and screenshot.
• SQLite for the database (it’s simple)
• Backblaze for storage
• BunnyCDN for cotent delivery
• Papertrail for logging

Deployment is done using Docker Compose, via SSH using the DOCKER_HOST environment variable pointing directly to a Raspberry Pi that I had bought and never used before. Now it saves me $5 per month, and I can keep a limited number of projects running on it.

And then you might ask: How do you expose it to the internet? I use Cloudflare Tunnel; the setup is simple and creates a direct connection between the Raspberry Pi and the nearest Point of Presence.

This type of hosting is extremely advantageous because the server’s IP and/or ports are never revealed; it stays behind my firewall. Everything goes through Cloudflare.

I have more than one Docker Compose file, and that’s what’s coolest. Locally, I run one, for deployment I instruct the Compose to read two others for logging and tunneling.

docker-compose.yaml

services:
  app:
    build: .
    env_file:
      - .env
    ports:
      - "8000:8000"
    restart: unless-stopped
    volumes:
      - data:/data
    tmpfs:
      - /tmp
volumes:
  data:

docker-compose.logging.yaml

services:
  app:
    logging:
      driver: syslog
      options:
        syslog-address: "udp://logs2.papertrailapp.com:XXX"

docker-compose.cloudflare.yaml

services:
  tunnel:
    image: cloudflare/cloudflared
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=yourtoken

Then for deploying

DOCKER_HOST=ssh://pi@192.168.0.10 docker compose --file docker-compose.yaml --file docker-compose.logging.yaml --file docker-compose.cloudflare.yaml up --build --detach

Example of the “worker queue”

package functions

import (
	"context"
	"database/sql"
	"fmt"
	"os"
	"os/exec"
	"path/filepath"
	"sync"
	"time"

	google "cloud.google.com/go/vision/apiv1"
	visionpb "cloud.google.com/go/vision/v2/apiv1/visionpb"
	"github.com/martinlindhe/base36"
	"github.com/minio/minio-go/v7"
	"github.com/minio/minio-go/v7/pkg/credentials"
	"github.com/playwright-community/playwright-go"
	"go.uber.org/zap"
	"google.golang.org/api/option"
	log "skhaz.dev/urlshortnen/logging"
)

var (
	accessKeyID     = os.Getenv("BACKBLAZE_ACCESS_ID")
	secretAccessKey = os.Getenv("BACKBLAZE_APPLICATION_KEY")
	bucket          = os.Getenv("BACKBLAZE_BUCKET")
	endpoint        = os.Getenv("BACKBLAZE_ENDPOINT")
	useSSL          = true
	extension       = "webp"
	mimetype        = "image/webp"
	quality         = "50"
)

type WorkerFunctions struct {
	db      *sql.DB
	vision  *google.ImageAnnotatorClient
	mc      *minio.Client
	browser playwright.BrowserContext
}

func Worker(db *sql.DB) {
	defer func() {
		if r := recover(); r != nil {
			log.Error("worker panic", zap.Any("error", r))
			time.Sleep(time.Second * 10)
			go Worker(db)
		}
	}()

	ctx := context.Background()

	vision, err := google.NewImageAnnotatorClient(ctx, option.WithCredentialsJSON([]byte(os.Getenv("GOOGLE_CREDENTIALS"))))
	if err != nil {
		log.Error("failed to create vision client", zap.Error(err))
		return
	}
	defer vision.Close()

	mc, err := minio.New(endpoint, &minio.Options{
		Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
		Secure: useSSL,
	})
	if err != nil {
		log.Error("failed to create minio client", zap.Error(err))
		return
	}

	pw, err := playwright.Run()
	if err != nil {
		log.Error("failed to launch playwright", zap.Error(err))
		return
	}
	//nolint:golint,errcheck
	defer pw.Stop()

	userDataDir, err := os.MkdirTemp("", "chromium")
	if err != nil {
		log.Error("failed to create temporary directory", zap.Error(err))
		return
	}
	defer os.RemoveAll(userDataDir)

	browser, err := pw.Chromium.LaunchPersistentContext(userDataDir, playwright.BrowserTypeLaunchPersistentContextOptions{
		Args: []string{
			"--headless=new",
			"--no-zygote",
			"--no-sandbox",
			"--disable-gpu",
			"--hide-scrollbars",
			"--disable-setuid-sandbox",
			"--disable-dev-shm-usage",
			"--disable-extensions-except=/opt/extensions/ublock,/opt/extensions/isdncac",
			"--load-extension=/opt/extensions/ublock,/opt/extensions/isdncac",
		},
		DeviceScaleFactor: playwright.Float(4.0),
		Headless:          playwright.Bool(false),
		Viewport: &playwright.Size{
			Width:  1200,
			Height: 630,
		},
		UserAgent: playwright.String("Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/125.0.0.0 Safari/537.36"),
	})
	if err != nil {
		log.Error("failed to launch chromium browser", zap.Error(err))
		return
	}
	defer browser.Close()

	wf := WorkerFunctions{
		db:      db,
		vision:  vision,
		mc:      mc,
		browser: browser,
	}

	for {
		start := time.Now()

		func() {
			var (
				wg   sync.WaitGroup
				rows *sql.Rows
				err  error
			)

			rows, err = db.Query("SELECT id, url FROM data WHERE ready = 0 ORDER BY created_at LIMIT 6")
			if err != nil {
				log.Error("error executing query", zap.Error(err))
				return
			}
			defer rows.Close()

			for rows.Next() {
				var id int64
				var url string
				if err = rows.Scan(&id, &url); err != nil {
					log.Error("error scanning row", zap.Error(err))
					return
				}

				wg.Add(1)
				go wf.run(&wg, url, id)
			}

			if err := rows.Err(); err != nil {
				log.Error("error during rows iteration", zap.Error(err))
				return
			}

			wg.Wait()
		}()

		elapsed := time.Since(start)
		if remaining := 5*time.Second - elapsed; remaining > 0 {
			time.Sleep(remaining)
		}
	}
}

func (wf *WorkerFunctions) run(wg *sync.WaitGroup, url string, id int64) {
	defer wg.Done()

	var message string

	if id < 0 {
		message = "invalid id: id must be non-negative"
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	var (
		ctx   = context.Background()
		short = base36.Encode(uint64(id))
	)

	dir, err := os.MkdirTemp("", "screenshot")
	if err != nil {
		message = fmt.Sprintf("failed to create temporary directory: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}
	defer os.RemoveAll(dir)

	var (
		fileName = fmt.Sprintf("%s.%s", short, extension)
		filePath = filepath.Join(dir, fileName)
	)

	page, err := wf.browser.NewPage()
	if err != nil {
		message = fmt.Sprintf("failed to create new page: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}
	defer page.Close()

	if _, err = page.Goto(url, playwright.PageGotoOptions{
		WaitUntil: playwright.WaitUntilStateDomcontentloaded,
	}); err != nil {
		message = fmt.Sprintf("failed to navigate to url: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	time.Sleep(time.Second * 5)

	title, err := page.Title()
	if err != nil {
		message = fmt.Sprintf("could not get title: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	description, err := page.Locator(`meta[name="description"]`).GetAttribute("content")
	if err != nil {
		log.Info("could not get meta description", zap.Error(err))
		description = ""
	}

	if _, err = page.Screenshot(playwright.PageScreenshotOptions{
		Path: playwright.String(filePath),
	}); err != nil {
		message = fmt.Sprintf("failed to create screenshot: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	fp, err := os.Open(filePath)
	if err != nil {
		message = fmt.Sprintf("failed to open screenshot: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}
	defer fp.Close()

	image, err := google.NewImageFromReader(fp)
	if err != nil {
		message = fmt.Sprintf("failed to load screenshot: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	annotations, err := wf.vision.DetectSafeSearch(ctx, image, nil)
	if err != nil {
		message = fmt.Sprintf("failed to detect labels: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	if annotations.Adult >= visionpb.Likelihood_POSSIBLE || annotations.Violence >= visionpb.Likelihood_POSSIBLE || annotations.Racy >= visionpb.Likelihood_POSSIBLE {
		message = fmt.Sprintf("site is not safe %v", annotations)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	cmd := exec.Command("convert", filePath, "-resize", "50%", "-filter", "Lanczos", "-quality", quality, filePath)
	if err := cmd.Run(); err != nil {
		message = fmt.Sprintf("error during image conversion: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	_, err = wf.mc.FPutObject(ctx, bucket, fileName, filePath, minio.PutObjectOptions{ContentType: mimetype})
	if err != nil {
		message = fmt.Sprintf("failed to upload file to minio: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	if _, err = wf.db.Exec("UPDATE data SET ready = 1, title = ?, description = ? WHERE url = ?", title, description, url); err != nil {
		message = fmt.Sprintf("failed to update database record: %v", err)
		log.Error(message)
		setError(wf.db, url, message)
		return
	}

	go warmup(fmt.Sprintf("%s/%s", os.Getenv("DOMAIN"), short))
}

func setError(db *sql.DB, url, message string) {
	if _, err := db.Exec("UPDATE data SET ready = 1, error = ? WHERE url = ?", message, url); err != nil {
		log.Error("failed to update database error record", zap.Error(err))
	}
}

It’s noticeable that it took a bit more effort than if I had used a task queue. However, it turned out to be quite robust and easy to debug, and for that reason alone, it was worth it.

Conclusion

In sharing the shortened link (https://takealook.pro/4MP) for my company Ultratech Software on social networks, you can have a really nice preview, as seen below.

Take A Look