Cyanide JS Tweaks

Writing a Tweak

Tweaks are plain .js files that run inside JavaScriptCore through Cyanide's SpringBoard RemoteCall bridge. 64-bit pointers are passed as hex strings (e.g. "0x105f2a000"). Wrap your code in an IIFE:

(() => {
  log("Hello from my tweak!");
  var cls = r_class("SBDockView");
  var dock = r_msg2(r_msg2(cls, "sharedInstance"), "dockView");
  r_msg2(dock, "setHidden:", 1);
})();

Parameters

Add @param comments at the top of your script. Cyanide parses them and generates native UI controls in Settings.

// @param: switch | enabled | Enable Tweak | true
// @param: slider | radius  | Corner Radius | 12.0 | 0.0-30.0
// @param: color  | tint    | Tint Color    | #FF6600
// @param: text   | label   | Custom Label  | Hello

Syntax: // @param: type | varName | Label | default | range
Types: switch (boolean), slider (float with min-max range), color (hex color picker), text (string input). Variables are injected at the top of your script before it runs.

RemoteCall API

These functions are injected into every JS context:

`log(message)`	Print to Cyanide's log console
`r_class(name)`	Get ObjC class pointer
`r_sel(name)`	String → SEL
`r_nsstr(str)`	Allocate NSString (release when done)
`r_msg2(t, s, a1..a4)`	Send ObjC message
`r_msg2_main(t, s, a1..a4)`	Send on main thread (use for views)
`r_responds(t, s)`	respondsToSelector check
`r_ivar_value(obj, name)`	Read instance variable
`r_pref_num(key)`	Read @param float value
`r_pref_bool(key)`	Read @param boolean value
`r_pref_str(key)`	Read @param string value

Timers: setInterval(fn, ms), clearInterval(id), setTimeout(fn, ms), clearTimeout(id) — mapped to GCD background queues so they never block the UI.

Color Allocation

64-bit IPC can't pass CGFloat arrays directly. Allocate colors through CIColor:

var hex = "#00FFCC".replace('#','');
var r = parseInt(hex.substring(0,2),16)/255;
var g = parseInt(hex.substring(2,4),16)/255;
var b = parseInt(hex.substring(4,6),16)/255;

var ciColorCls = r_class("CIColor");
var color = r_msg2(ciColorCls, "colorWithRed:green:blue:alpha:", r, g, b, 1.0);
var uiColor = r_msg2(r_class("UIColor"), "colorWithCIColor:", color);

Tips

• Always use r_msg2_main for view manipulation — r_msg2 on a background thread can crash SpringBoard.
• Release r_nsstr allocations to avoid leaking memory in the SpringBoard process.
• Use r_responds to check selectors before calling — iOS versions differ.
• Test scripts locally with QuickLoader before adding them to your repo.
• HTTPS is required for all script and repo URLs — Cyanide rejects HTTP.

Setting Up a Repo

Host a JSON file on any HTTPS server. Users add the URL in Cyanide's Sources tab. No server-side code needed — GitHub Pages or any static host works.

{
  "repoName": "My Repo",
  "author": "yourname",
  "tweaks": [
    {
      "id": "me.my-tweak",
      "name": "My Tweak",
      "description": "What it does",
      "version": "1.0.0",
      "symbol": "sparkle",
      "author": "tweakauthor",
      "scriptURL": "https://example.com/tweak.js"
    }
  ]
}

Required: repoName, author, tweaks[].id, tweaks[].name, tweaks[].description, tweaks[].version, tweaks[].scriptURL
Optional: tweaks[].symbol (SF Symbol name for icon), tweaks[].author (per-tweak author override). Custom icon images planned for a future update.

Hosting & Updating

GitHub Pages setup:
1. Create a public GitHub repo
2. Add your .js tweak files and a JSON index (e.g. tweaks.json)
3. Point scriptURL to the raw files: https://yourname.github.io/repo/tweak.js
4. Enable GitHub Pages in repo Settings (Source: main branch, root folder)
5. Share the JSON URL with users

Pushing updates:
1. Update the .js file at the same URL
2. Bump the version string in the JSON
3. Commit and push — Cyanide checks for updates every few hours and shows an update badge

Multiple tweaks: add more entries to the tweaks array. Each needs a unique id and scriptURL. Use descriptive IDs like "yourname.tweakname" to avoid collisions.

Cyanide JS Tweaks

Developer Docs