patch-anatomy
/patch-anatomy
How to write Morphe patches — bytecodePatch DSL, compatibility, extensions, options, finalization. Use when creating new patches or understanding patch structure.
- Author
- paresh-maheshwari ↗
- Repository
- morphe-ai ↗
- Licence
- GPL-3.0
- Last repository change
- 29.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.
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
- Patch Types
- Complete Patch Example
- addInstructions — Deprecation Note
- Patch Options
- Extensions (Runtime DEX Code)
- Finalization Order
- Compatibility Declaration
- ApkFileType Values
- AppTarget
- Patch Availability API
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…