Skip to content
Skills Library
Programming · Learning & explanation

patch-anatomy

/patch-anatomy

How to write Morphe patches — bytecodePatch DSL, compatibility, extensions, options, finalization. Use when creating new patches or understanding patch structure.

Repository
morphe-ai ↗
Licence
GPL-3.0
Last repository change
29.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

How to write Morphe patches — bytecodePatch DSL, compatibility, extensions, options, finalization. Use when creating new patches or understanding patch structure.

Original author description

How to write Morphe patches — bytecodePatch DSL, compatibility, extensions, options, finalization. Use when creating new patches or understanding patch structure.

How it works

  1. Patch Types
  2. Complete Patch Example
  3. addInstructions — Deprecation Note
  4. Patch Options
  5. Extensions (Runtime DEX Code)
  6. Finalization Order
  7. Compatibility Declaration
  8. ApkFileType Values
  9. AppTarget
  10. Patch Availability API
Original SKILL.md headings · 291 lines, 1,071 words
SKILL.md preview
---
name: patch-anatomy
description: How to write Morphe patches — bytecodePatch DSL, compatibility, extensions, options, finalization. Use when creating new patches or understanding patch structure.
---

> **When to use:** Writing patches — bytecodePatch DSL, compatibility declarations, extensions, options, finalization. Keep patches minimal — put complex logic in extensions.

# Morphe Patch Anatomy — Official Reference

> ⚠️ Pinned source: morphe-patcher `6f189f9`. Official docs may lag the source — the pinned
> source wins if anything contradicts this file.

## Patch Types

| Type | Use When | Performance |
|------|----------|-------------|
| `bytecodePatch` | Modifying Dalvik bytecode | Fast — no resource decoding |
| `rawResourcePatch` | Modifying raw files/assets | Medium |
| `resourcePatch` | Modifying decoded XML | Slow — decodes all resources |

Always prefer `bytecodePatch`.

## Complete Patch Example

```kotlin
val COMPATIBILITY_XYZ = Compatibility(
    packageName = "app.xyz.mobile",
    name = "XYZ App",
    apkFileType = ApkFileType.XAPK,
    appIconColor = 0xFF3300,   // 0xRRGGBB — six-digit hex, zero alpha byte
    targets = listOf(
        AppTarget(version = "2.0.0"),
        AppTarget(version = "1.0.42"),
    )
)

@Suppress("unused")
val disableAdsPatch = bytecodePatch(
    name = "Disable ads",
    description = "Disables ads in the app.",
    default = true               // omit or set false for universal patches (enforced by builder)
) {
    compatibleWith(COMPATIBILITY_XYZ)
    dependsOn(disableAdsResourcePatch)
    extendWith("disable-ads.mpe")   // ← extension artifact is .mpe, not .mpp

    execute {
        showAdsFingerprint.method.addInstructions(0, """
            invoke-static {}, LDisableAdsPatch;->shouldDisableAds()Z
            move-result v0
            return v0
        """)
    }

    finalize {
        // Post-processing after all dependent patches execute
    }
}
```

## `addInstructions` — Deprecation Note

`addInstructions(String)` (no-index form) is **deprecated**. Always supply the index:

```kotlin
// ✅ Current
method.addInstructions(0, "const/4 v0, 0x1\nreturn v0")

// ❌ Deprecated — will be deleted
method.addInstructions("const/4 v0, 0x1\nreturn v0")
```

## Patch Options

```kotlin
val patch = bytecodePatch(name = "Configurable") {
    val value by stringOption(name = "Color")
    val custom by option<String>(name = "Custom option")
    execute { println(value) }
}
```

Options can be shared across patches:
```kotlin
val sharedOption = stringOption(name = "Shared")
bytecodePatch(name = "A") { val v by sharedOption() }
bytecodePatch(name = "B") { val v by sharedOption() }
```

## Extensions (Runtime DEX Code)

Extensions are precompiled DEX files (`.mpe`) merged into the patched app before patch execution.

```java
public class ComplexPatch {
    public static void doSomething() { /* complex logic */ }
}
```

Referenced in patches:
```kotlin
val patch = bytecodePatch(name = "Complex") {
    extendWith("complex-patch.mpe")   // ← .mpe not .mpp
    execute {
        fingerprint.method.addInstructions(0, "invoke-static {}, LComplexPatch;->doSomething()V")
    }
}
```

### `extendWithAll` — variable extension count

When the set of extensions is not known until patch time (e.g., determined by a dependency):
```kotlin
extendWithAll(Supplier { listOf(stream1, stream2) })
```

## Finalization Order

```kotlin
val patch = bytecodePatch(name = "Main") {
    dependsOn(bytecodePatch(name = "Dep") {
        execute { print("1") }
        finalize { print("4") }
    })
    execute { print("2") }
    finalize { print("3") }
}
// Output: 1234 (execute in dependency order, finalize in reverse)
```

## Compatibility Declaration

```kotlin
val COMPAT = Compatibility(
    packageName = "com.example.app",  // must match Android package name regex
    name = "App Name",                // required when packageName is non-null, must be non-blank
    description = "Optional description.",
    apkFileType = ApkFileType.XAPK,   // see ApkFileType below
    appIconColor = 0x6200EE,          // 0xRRGGBB — alpha byte MUST be 0x00
    signatures = setOf(
        "a1b2c3...64hexchars"         // SHA-256 from apksigner verify --print-certs, 64 hex chars
    ),
    targets = listOf(                 // must be non-empty; newest first
        AppTarget(version = "2.0.0", minSdk = 28, isExperimental = true),
        AppTarget(version = "1.0.0", minSdk = 26),
    )
)
```

### Rules
- `packageName` + `name` go together — if `packageName` is set, `name` must also be non-blank.
- `appIconColor` is `0xRRGGBB` (six-digit). The alpha byte must be `0x00` (zero) or the
  constructor throws. E.g. `0x6200EE` ✅, `0xFF6200EE` ❌.
- `signatures` — each string must be exactly 64 hex characters (SHA-256).
- `targets` — must be non-empty. Use `AppTarget(version = null)` for "any version".
- Duplicate versions in `targets` throw `IllegalArgumentException`.

### `including` / `excluding`

```kotlin
val COMPAT_PLUS = COMPAT.including(AppTarget(version = "3.0.0"))
val COMPAT_MINUS = COMPAT.excluding("1.0.0", "1.0.42")
```

## ApkFileType Values

```kotlin
enum class ApkFileType {
    APK,           // single APK (recommended)
    APK_REQUIRED,  // single APK (required — other formats rejected)
    APKM,          // APKMirror bundle (recommended)
    APKM_REQUIRED, // APKMirror bundle (required)
    APKS,          // bundletool APKS (recommended)
    APKS_REQUIRED, // bundletool APKS (required)
    XAPK,          // APKPure XAPK (recommended)
    XAPK_REQUIRED, // APKPure XAPK (required)
}
```

Non-`_REQUIRED` variants are recommendations; `_REQUIRED` variants enforce the format.

## AppTarget

```kotlin
data class AppTarget(
    val version: String?,                         // null = any version
    val versionCodes: Map<SupportedAbi, Int>? = null,
    val isExperimental: Boolean = false,
    val minSdk: Int? = null,
    val description: String? = null,
)

enum class SupportedAbi { ARM64_V8A, ARMEABI_V7A, X86_64, X86 }
```

`versionCodes` is only needed for apps that ship multiple releases per user-visible version
(e.g., Meta apps). Pass a single `Int` overload to use the same code for all ABIs:

```kotlin
AppTarget(version = "2.0.0", versionCode = 20000)
// expands to Map<SupportedAbi, Int> for all entries
```

## Patch Availability API

Declare how a patch behaves for a given install target (Manager / CLI evaluates before selection):

```kotlin
import app.morphe.patcher.patch.InstallerType      // STANDARD, MOUNT, SHIZUKU
import app.morphe.patcher.patch.ApkArchitecture    // ARM64_V8A, ARMEABI_V7A, X86_64, X86, UNIVERSAL
import app.morphe.patcher.patch.PatchAvailability  // ENABLED, DISABLED, REQUIRED, UNAVAILABLE
import app.morphe.patcher.patch.AvailabilityResolver

val patch = bytecodePatch(name = "Root Only Feature") {
    availability { installer, arch ->
        if (installer == InstallerType.MOUNT) PatchAvailability.ENABLED
        else PatchAvailability.UNAVAILABLE
    }
    execute { /* … */ }
}
```

Patches without an `availability` block fall back to their `default` flag.

## `category`

Optional free-form group for UI display:

```kotlin
val patch = bytecodePatch(name = "Remove Banner Ads") {
    category("Ads")
    execute { /* … */ }
}
```

## `default` Flag Warning

Universal patches (no `compatibleWith`) with `default = true` are overridden to `false` with a
console warning at build time. Always set `default = false` for universal patches.

## Project Structure

```
patches/src/main/kotlin/app/<group>/patches/
├── shared/              # Shared across all apps
├── <app>/
│   ├── shared/Constants.kt
│   └── <category>/
│       ├── Fingerprints.kt
│       └── SomePatch.kt
extensions/<name>/src/main/java/   # Extension code (produces .mpe)
```

## Conventions

- Name patches after what they do: "Disable ads", "Remove watermark"
- Description in third person, present tense, ending with period
- Name fingerprints with best guess of target method purpose
- Keep patches minimal — put complex logic in extensions
- Add `@Suppress("unused")` on top-level patch vals
- Document non-obvious code

## Key Imports

```kotlin
import app.morphe.patcher.Fingerprint
import app.morphe.patcher.string
import app.morphe.patcher.methodCall
import app.morphe.patcher.fieldAccess
import app.morphe.patcher.newInstance
import app.morphe.patcher.instanceOf
import app.morphe.patcher.checkCast
import app.morphe.patcher.opcode
import app.morphe.patcher.literal
import app.morphe.patcher.resourceLiteral
import app.morphe.patcher.anyInstruction
import app.morphe.patcher.extensions.InstructionExtensions.addInstruction
import app.morphe.patcher.extensions.InstructionExtensions.addInstructions
import app.morphe.patcher.extensions.InstructionExtensions.addInstructionsWithLabels
import app.morphe.patcher.extensions.InstructionExtensions.getInstruction
import app.morphe.patcher.patch.bytecodePatch
import app.morphe.patcher.patch.rawResourcePatch
import app.morphe.patcher.patch.resourcePatch
import app.morphe.patcher.patch.ApkFileType
import app.morphe.patcher.patch.AppTarget
import app.morphe.patcher.patch.Compatibility
import app.morphe.patcher.patch.InstallerType
import app.morphe.patcher.patch.ApkArchitecture
import app.morphe.patcher.patch.PatchAvailability
import com.android.tools.smali.dexlib2.AccessFlags
import com.android.tools.smali.dexlib2.Opcode
import com.android.tools.smali.dexlib2.iface.instruction.OneRegisterInstruction
import com.android.tools.smali.dexlib2.iface.instruction.TwoRegisterInstruction
```

Versions

The database has no other skills named patch-anatomy.

Database snapshot: 13.11.2026 · package version cc9ac43e6ba3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95morphe-cli-reference
    Morphe CLI v1.17.0 (morphe-desktop) complete command reference — patch, list-patches, list-versions, options-create, utility install/uninstall. Use when running CLI commands, testing patches, or troubleshooting CLI usage.
  • 90real-patch-examples
    Real-world Morphe patch patterns from official morphe-patches repo — method override, list filtering, return value override, class chaining, dynamic fingerprints, string replacement. Use when writing patches and need pattern reference.
  • 100patch-creation
    Create and register new patches for tweakcc. Use when adding new customizations to Claude Code.
  • 100generating-patches
    Generates git patch files from codebase modifications for local application. Use when user mentions patch, diff, export changes, bring changes back, apply locally, or after editing uploaded codebases.
  • 100security-patch-workflow
    How to create, apply, and verify security patches for git repositories. Use this skill when creating patches from code changes, applying patches to source code, or validating that patches correctly address vulnerabilities.
  • 90evo-patch-generate-apply
    Generates git-compatible unified diff patches from original and modified file contents, writes them to numbered patch files, and applies them to the repository using git apply or GNU patch. Use when you need to create code patches, apply fixes to source files, or automate code…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.