netip.Addr features an Unmap() method returning the unwrapped IPv4 contained in an IPv4-mapped IPv6 address: from ::ffff:203.0.113.10 or ::ffff:cb00:710a, it returns 203.0.113.10.¹ There is no Map() or To6() method for the reverse direction. Such a method is trivial to implement, but Go maintainers have rejected it on the grounds that users should write netip.AddrFrom16(ip.As16()) and let the compiler optimize it.² Today, this pattern is eight times slower than a native method. How can we teach the compiler to optimize this sequence?

The alternatives
Hacking the Go compiler
- The hammer
- The screwdriver
Next steps

The alternatives

Let’s explore three ways to implement the map semantics for netip.Addr. My favorite is to add it to the Go standard library. Go maintainers prefer a small external helper chaining netip.AddrFrom16() and netip.Addr.As16(), hoping the compiler eventually optimizes it. The unsafe package opens a third path, with the same performance as the first solution.

Modifying the Go standard library

Internally, netip.Addr stores any IP address as a 128-bit value with an extra field z to encode the family and the zone:

type Addr struct {
    addr uint128
    z unique.Handle[addrDetail]
}

type addrDetail struct {
    isV6   bool   // IPv4 is false, IPv6 is true.
    zoneV6 string // != "" only if IsV6 is true.
}

var (
    z0    unique.Handle[addrDetail]
    z4    = unique.Make(addrDetail{})
    z6noz = unique.Make(addrDetail{isV6: true})
)

AddrFrom4() encodes an IPv4 address as an IPv4-mapped IPv6 address and sets z to the unique value z4:

// AddrFrom4 returns the address of the IPv4 address given by the bytes in addr.
func AddrFrom4(addr [4]byte) Addr {
    return Addr{
        addr: uint128{
            0,
            0xffff00000000 |
                uint64(addr[0])<<24 | uint64(addr[1])<<16 |
                uint64(addr[2])<<8 | uint64(addr[3])},
        z: z4,
    }
}

Unmap() turns an IPv4-mapped IPv6 address into an IPv4 address by setting the z field to z4:

func (ip Addr) Unmap() Addr {
    if ip.Is4In6() {
        ip.z = z4
    }
    return ip
}

Implementing the reverse direction inside the Go standard library is trivial: we set the z field to z6noz if the address is IPv4.

// To6 maps an IPv4 address to an IPv4-mapped IPv6 address. It returns an
// IPv6 address unmodified.
func (ip Addr) To6() Addr {
    if ip.Is4() {
        ip.z = z6noz
    }
    return ip
}

As a helper

We can’t access the z field from outside the net/netip package. Instead, we build a small helper around the netip.AddrFrom16(ip.As16()) pattern:

// AddrTo6 maps an IPv4 address to an IPv4-mapped IPv6 address. It returns an
// IPv6 address unmodified.
func AddrTo6(ip netip.Addr) netip.Addr {
    if ip.Is4() {
        ip = netip.AddrFrom16(ip.As16())
    }
    return ip
}

As an unsafe function

Another solution uses the unsafe package to alter the Addr struct through a proxy with the same memory layout:³

// addrProxy has the same memory layout as netip.Addr.
type addrProxy struct {
    addr [2]uint64      // netip.uint128
    z    unsafe.Pointer // unique.Handle[netip.addrDetail]
}

var (
    anyIPv6    = netip.IPv6Unspecified()
    netipZ6noz = (*addrProxy)(unsafe.Pointer(&anyIPv6)).z
)

// AddrTo6 maps an IPv4 address to an IPv4-mapped IPv6 address. It returns an
// IPv6 address unmodified.
func AddrTo6(ip netip.Addr) netip.Addr {
    if !ip.Is4() {
        return ip
    }
    (*addrProxy)(unsafe.Pointer(&ip)).z = netipZ6noz
    return ip
}

Benchmarks

On my computer, with Go 1.27.1, the standard library solution costs 0.88 ns per operation, while the solution favored by Go maintainers costs 7.14 ns. The unsafe solution matches the performance of the first one.

goos: linux
goarch: amd64
pkg: github.com/vincentbernat/go-netip-addrto6
cpu: AMD Ryzen 5 5600X 6-Core Processor
                   │     sec/op     │
AddrTo6/safe            7.137n ± 0%
AddrTo6/unsafe         0.8682n ± 2%
AddrTo6/builtin        0.8775n ± 2%

Assembly code

Let’s check the assembly code the compiler generates for each solution.⁴ The one built into the standard library looks like this:⁵

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
 CMPQ  net/netip·z4(SB), CX     ; check "z" if this is an IPv4 address
 JNE   end                      ; if not, stop here
 MOVQ  net/netip·z6noz(SB), CX  ; CX = netip.z6noz
end:
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

Go’s assembly language is not a direct representation of the underlying machine language: it operates on a semi-abstract instruction set derived from Plan 9’s assembler. It has four pseudo-registers: FP (frame pointer for function arguments), PC (program counter), SB (static base pointer for global symbols), and SP (stack pointer). It also has architecture-specific registers like AX, CX, DX, BX, SI, DI, and R8 to R15. Instructions storing data use their last argument as the destination. Instructions can carry an explicit size suffix: MOVB moves a byte, MOVW 16 bits, MOVL 32 bits, and MOVQ 64 bits. In the example above, the first instruction compares the 64-bit value z4 with the CX register.

The unsafe solution looks almost the same:

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
 CMPQ  net/netip·z4(SB), CX  ; check "z" if this is an IPv4 address
 JNE   end                   ; if not, stop here
 MOVQ  netipZ6noz(SB), CX    ; CX = netip.z6noz
end:
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

The helper solution has far more instructions. To understand why, let’s look at the code for As16() and AddrFrom16(). They are short enough for the compiler to inline them.

func (ip Addr) As16() (a16 [16]byte) {
    byteorder.BEPutUint64(a16[:8], ip.addr.hi)
    byteorder.BEPutUint64(a16[8:], ip.addr.lo)
    return a16
}

func AddrFrom16(addr [16]byte) Addr {
    return Addr{
        addr: uint128{
            byteorder.BEUint64(addr[:8]),
            byteorder.BEUint64(addr[8:]),
        },
        z: z6noz,
    }
}

We can already guess the pattern to optimize: the code packs the IP address into an array, copies it, then unpacks it. If we inline the Go code by hand, we get:

func AddrTo6(input netip.Addr) netip.Addr {
    if !input.Is4() {
        return input
    }

    var a16 [16]byte
    byteorder.BEPutUint64(a16[:8], input.addr.hi)
    byteorder.BEPutUint64(a16[8:], input.addr.lo)

    addr := a16

    var output netip.Addr
    output.addr.hi = byteorder.BEUint64(addr[:8])
    output.addr.lo = byteorder.BEUint64(addr[8:])
    output.z = netip.z6noz
    return output
}

As humans, we can mentally derive the optimized form:

func AddrTo6(input netip.Addr) netip.Addr {
    if !input.Is4() {
        return input
    }
    var output netip.Addr
    output.addr.hi = input.addr.hi
    output.addr.lo = input.addr.lo
    output.z = netip.z6noz
    return output
}

Unfortunately, as of Go 1.26.8, the compiler is not smart enough to do the same:

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
; Push the stack (32 bytes):
;    0(SP) addr netip.uint128
;   16(SP) a16 [16]byte
 PUSHQ   BP
 MOVQ    SP, BP
 SUBQ    $32, SP

 CMPQ    net/netip·z4(SB), CX  ; check "z" if this is an IPv4 address
 JNE     end                   ; if not, stop here

; Pack: byteorder.BEPutUint64(a16[:8], input.addr.hi)
;       byteorder.BEPutUint64(a16[8:], input.addr.lo)
 MOVBEQ  AX, net/netip·a16+16(SP)
 MOVBEQ  BX, net/netip·a16+24(SP)

; addr = a16, 16 bytes at once through the vector register X0
 MOVUPS  net/netip·a16+16(SP), X0
 MOVUPS  X0, net/netip·addr(SP)

; CX = netip.z6noz
 MOVQ    net/netip·z6noz(SB), CX
; Unpack: output.addr.hi = byteorder.BEUint64(addr[:8])
;         output.addr.lo = byteorder.BEUint64(addr[8:])
 MOVBEQ  net/netip·addr(SP), AX
 MOVBEQ  net/netip·addr+8(SP), BX

end:
 ADDQ    $32, SP
 POPQ    BP
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

The compiler does a decent job on the byte shuffling: the eight byte stores of BEPutUint64() become a single MOVBEQ, which stores a register byte-swapped. The eight byte loads of BEUint64() become a single MOVBEQ the other way round.⁶ Three groups of instructions remain: a pack, a copy, and an unpack.

Hacking the Go compiler

The Go compiler has several phases:

Parsing: The compiler tokenizes and parses the source code. It builds a syntax tree for each source file.
Type checking: The compiler maps each identifier to the object it denotes, folds constants, and infers the type of every expression.
IR construction: The compiler converts the syntax tree and its types into its own intermediate representation (IR). This process, called “noding,” goes through a serialization format named unified IR.
Middle end: The compiler performs several optimization passes on the IR, such as devirtualization, function call inlining, and escape analysis.
Walk: This phase runs two steps: order of evaluation decomposes complex statements into simpler ones, and desugaring transforms higher-level Go constructs, like switch or channels, into more primitive instructions or calls to the runtime.
Generic SSA: The compiler converts the IR into Static Single Assignment (SSA) form, a lower-level intermediate representation suited for machine-independent optimizations and rewrite rules.
Machine code generation: The compiler rewrites the SSA form into machine-specific variants, allocates registers, and applies more optimization passes. At the end, the assembler turns the generated instructions into machine code.

The hammer

My first idea is to replace occurrences of netip.AddrFrom16(ip.As16()) with netip.Addr{addr: ip.addr, z: netip.z6noz} as early as possible, during the “noding” process. Before that, the type checking phase prevents us from accessing unexported struct fields.

Go 1.27 introduced a convenient debug option to dump the IR of a function at interesting points during compilation:

$ GOTOOLCHAIN=go1.27.1 GOAMD64=v3 go build -a -gcflags="-d=astdump=AddrTo6Safe" .
Writing text ast output for AddrTo6Safe to AddrTo6Safe.ast
Writing html ast output for AddrTo6Safe to AddrTo6Safe.html
Writing html syntax output for AddrTo6Safe to AddrTo6Safe.syntax.html

In the HTML file, the first column shows the IR as it comes out of noding:

DCLFUNC addrto6.AddrTo6Safe ABI:ABIInternal FUNC-func(netip.Addr) netip.Addr
DCLFUNC-Dcl
. NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. NAME-addrto6.~r0 Class:PPARAMOUT Offset:0 OnStack netip.Addr
DCLFUNC-body
. IF # ipv6_safe.go:11:2
. IF-Cond
. . CALLFUNC bool
. . CALLFUNC-Fun
. . . METHEXPR addrto6.Is4 FUNC-func(netip.Addr) bool
. . . . TYPE netip.Addr Class:PEXTERN Offset:0 type netip.Addr
. . CALLFUNC-Args
. . . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. IF-Body
. . AS # ipv6_safe.go:12:6
. . . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. . . CALLFUNC netip.Addr
. . . CALLFUNC-Fun
. . . . NAME-netip.AddrFrom16 Class:PFUNC Offset:0 Used FUNC-func([16]byte) netip.Addr
. . . CALLFUNC-Args
. . . . CALLFUNC ARRAY-[16]byte
. . . . CALLFUNC-Fun
. . . . . METHEXPR addrto6.As16 FUNC-func(netip.Addr) [16]byte
. . . . . . TYPE netip.Addr Class:PEXTERN Offset:0 type netip.Addr
. . . . CALLFUNC-Args
. . . . . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. RETURN # ipv6_safe.go:14:2
. RETURN-Results
. . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr

In the body of the if statement, we spot the calls to the method netip.Addr.As16() and to the function netip.AddrFrom16(). Our goal is to patch them with a struct literal:

IF-Body
. AS # ipv6_safe.go:12:6
. . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. . STRUCTLIT netip.Addr
. . STRUCTLIT-List
. . . STRUCTKEY netip.addr
. . . . DOT netip.addr netip.uint128
. . . . . NAME-addrto6.ip Class:PPARAM Offset:0 OnStack Used netip.Addr
. . . STRUCTKEY netip.z
. . . . NAME-netip.z6noz Class:PEXTERN Offset:0 unique.Handle[net/netip.addrDetail]

In noder’s reader.go, the expr() method builds the IR tree for an expression. At the end of the exprCall case, we add a call to a rewriteAddrFrom16As16() function. It takes the current node and returns the struct literal on success, or nil if the rewrite is not possible. First, we check that we have the expected pattern: a call to the netip.AddrFrom16() function with a call to the netip.Addr.As16() method as its only argument:

func rewriteAddrFrom16As16(n ir.Node) ir.Node {
    call, ok := n.(*ir.CallExpr)
    if !ok || call.Op() != ir.OCALLFUNC ||
        len(call.Args) != 1 || len(call.Init()) != 0 ||
        !isNetipFunc(call.Fun, "AddrFrom16") {
        return nil
    }
    inner, ok := call.Args[0].(*ir.CallExpr)
    if !ok || inner.Op() != ir.OCALLFUNC ||
        len(inner.Args) != 1 || len(inner.Init()) != 0 ||
        !isNetipFunc(inner.Fun, "Addr.As16") {
        return nil
    }
    x := inner.Args[0]
    // [...]
}

Then, we fetch netip.z6noz:

z6noz, err := lookupVar(ir.StaticCalleeName(call.Fun).Sym().Pkg, "z6noz")
if err != nil {
    return nil
}

And we build the struct literal:

typ := call.Type()
pos := call.Pos()
var list []ir.Node
for i, f := range typ.Fields() {
    var value ir.Node
    switch f.Sym.Name {
    case "addr":
        value = typecheck.DotField(pos, x, i)
    case "z":
        value = z6noz
    default:
        return nil
    }
    list = append(list, ir.NewStructKeyExpr(pos, f, value))
}
lit := ir.NewCompLitExpr(pos, ir.OSTRUCTLIT, typ, list)
lit.SetTypecheck(1)
return lit

Have a look at the complete patch.⁷ We can test it with the following commands:

$ cd src
$ ./make.bash
Building Go cmd/dist using /usr/lib/go-1.27. (go1.27.1 linux/amd64)
Building Go toolchain1 and bootstrap cmd/go (go_bootstrap) using /usr/lib/go-1.27.
Building Go toolchain2 using go_bootstrap and Go toolchain1.
Building Go toolchain3 and commands using go_bootstrap and Go toolchain2.
Checking command staleness for linux/amd64.
---
Installed Go for linux/amd64 in /home/bernat/code/free/go
Installed commands in /home/bernat/code/free/go/bin
*** You need to add /home/bernat/code/free/go/bin to your PATH.
$ export PATH=$PWD/../bin:$PATH
$ go version
go version go1.28-devel_9834516e20 Sat Sep 12 08:23:11 2026 -0700 linux/amd64
$ go test net/netip/...
ok      net/netip   0.224s
$ cd ../../go-netip-addrto6
$ go test .
ok      github.com/vincentbernat/go-netip-addrto6   0.062s

The generated code for the helper is now the shortest possible version!

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
 CMPQ    net/netip·z4(SB), CX     ; check "z" if this is an IPv4 address
 JNE     end                      ; if not, stop here
 MOVQ    net/netip·z6noz(SB), CX  ; CX = netip.z6noz
end:
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

Go maintainers are unlikely to accept this change. It relies on the internal structure of net/netip.Addr. It’s an ugly hack in the noder, whose job is to faithfully translate the type-checked AST into the IR. And it’s harder to maintain than adding a To6() method.

The screwdriver

The right place for such an optimization is the generic SSA phase. One of the last machine-independent passes is memcombine. With the appropriate debug flag, the compiler dumps the SSA form after this pass:⁸

$ GOTOOLCHAIN=go1.26.8 GOAMD64=v3 \
> go build -a -gcflags='-d=ssa/memcombine/dump=AddrTo6Safe' .
$ head -5 AddrTo6Safe_01__memcombine.dump
AddrTo6Safe func(netip.Addr) netip.Addr
  b2:
    (?) v1 = InitMem <mem>
    (?) v2 = SP <uintptr>
    (?) v3 = SB <uintptr>

The result of the memcombine pass follows the same structure as the assembly code for AddrTo6Safe() we looked at earlier: two stores, one move, and two loads we would like to optimize away.

; […]
  v502 = ArgIntReg <uint64> {ip+0} [0]              ; input.addr.hi
  v490 = ArgIntReg <uint64> {ip+8} [1]              ; input.addr.lo
  v466 = ArgIntReg <*netip.addrDetail> {ip+16} [2]  ; input.z
; […]
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v442 = Bswap64 <uint64> v490                      ; bswap(input.addr.lo)
  v542 = Bswap64 <uint64> v502                      ; bswap(input.addr.hi)
  v161 = Store <mem> {uint64} v22 v542 v23          ; a16[:8] = bswap(hi)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)

  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16

  v415 = OffPtr <*byte> [8] v285                    ; &addr[8]
  v416 = Load <uint64> v285 v286                    ; addr[:8]
  v299 = Bswap64 <uint64> v416                      ; output.addr.hi
  v174 = Load <uint64> v415 v286                    ; addr[8:]
  v39  = Bswap64 <uint64> v174                      ; output.addr.lo
; […]

Each line features a value identifier (v442), an operation with its type (Bswap64 <uint64>), and its arguments (v490).⁹ Values are the basic building blocks of SSA and are defined exactly once. Square brackets enclose integer parameters ([8]) and curly braces contain auxiliary arguments ({netip.addr}). Operations writing to memory produce a new memory state. Every memory operation takes the current state as its last argument, which keeps them in order.

On paper

Let’s focus on output.addr.lo, aka v39:

  v490 = ArgIntReg <uint64> {ip+8} [1]              ; input.addr.lo
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v442 = Bswap64 <uint64> v490                      ; bswap(input.addr.lo)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v415 = OffPtr <*byte> [8] v285                    ; &addr[8]
  v174 = Load <uint64> v415 v286                    ; addr[8:]
  v39  = Bswap64 <uint64> v174                      ; output.addr.lo

To simplify this code, we could apply three rewriting rules:

The first one adds a shortcut when loading through a move: (Load (OffPtr [o] p) (Move p src mem)) => (Load (OffPtr [o] src) mem). This matches v174 with its arguments v415 and v286 and creates a new value v600:

  v490 = ArgIntReg <uint64> {ip+8} [1]              ; input.addr.lo
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v442 = Bswap64 <uint64> v490                      ; bswap(input.addr.lo)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v415 = OffPtr <*byte> [8] v285                    ; &addr[8]
  v600 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v174 = Load <uint64> v600 v282                    ; a16[8:]
  v39  = Bswap64 <uint64> v174                      ; output.addr.lo

The second one simplifies a load following a store: (Load p (Store p x _)) => x. The load is forwarded: the stored value replaces it and no memory access remains. It matches v174. It notices that v600 and v173 are the same address and replaces v174 with a copy of v442:

  v490 = ArgIntReg <uint64> {ip+8} [1]              ; input.addr.lo
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v442 = Bswap64 <uint64> v490                      ; bswap(input.addr.lo)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v415 = OffPtr <*byte> [8] v285                    ; &addr[8]
  v600 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v174 = Copy <uint64> v442                         ; bswap(input.addr.lo)
  v39  = Bswap64 <uint64> v174                      ; output.addr.lo

The last step cancels the two byte swaps: (Bswap64 (Bswap64 x)) => x. v39 becomes a copy of v490:

  v490 = ArgIntReg <uint64> {ip+8} [1]              ; input.addr.lo
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v442 = Bswap64 <uint64> v490                      ; bswap(input.addr.lo)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v415 = OffPtr <*byte> [8] v285                    ; &addr[8]
  v600 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v174 = Copy <uint64> v442                         ; bswap(input.addr.lo)
  v39  = Copy <uint64> v490                         ; output.addr.lo = input.addr.lo

If we ignore the values not needed to compute v39, only this SSA form remains:

  v490 = ArgIntReg <uint64> {ip+8} [1]  ; input.addr.lo
  v39  = Copy <uint64> v490             ; output.addr.lo = input.addr.lo

Let’s switch to output.addr.hi, aka v299:

  v502 = ArgIntReg <uint64> {ip+0} [0]              ; input.addr.hi
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v542 = Bswap64 <uint64> v502                      ; bswap(input.addr.hi)
  v161 = Store <mem> {uint64} v22 v542 v23          ; a16[:8] = bswap(hi)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v416 = Load <uint64> v285 v286                    ; addr[:8]
  v299 = Bswap64 <uint64> v416                      ; output.addr.hi

To optimize it away, we also apply three rewriting rules:

The first one also adds a shortcut when loading through a move, but without an offset: (Load p (Move p src mem)) => (Load src mem). This rewrites v416 to use arguments from v286:

  v502 = ArgIntReg <uint64> {ip+0} [0]              ; input.addr.hi
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v542 = Bswap64 <uint64> v502                      ; bswap(input.addr.hi)
  v161 = Store <mem> {uint64} v22 v542 v23          ; a16[:8] = bswap(hi)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v416 = Load <uint64> v22 v282                     ; a16[:8]
  v299 = Bswap64 <uint64> v416                      ; output.addr.hi

The second rule forwards a value stored one step earlier, skipping over a store to another address: (Load p (Store q _ (Store p x _))) => x. This matches v416: x is v542, p is v22 (&a16), q is v173 (&a16[8]), and p and q do not overlap for uint64.

  v502 = ArgIntReg <uint64> {ip+0} [0]              ; input.addr.hi
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v542 = Bswap64 <uint64> v502                      ; bswap(input.addr.hi)
  v161 = Store <mem> {uint64} v22 v542 v23          ; a16[:8] = bswap(hi)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v416 = Copy <uint64> v542                         ; bswap(input.addr.hi)
  v299 = Bswap64 <uint64> v416                      ; output.addr.hi

The third rule cancels two byte swaps: (Bswap64 (Bswap64 x)) => x. v299 becomes a copy of v502:

  v502 = ArgIntReg <uint64> {ip+0} [0]              ; input.addr.hi
  v22 = LocalAddr <*[16]byte> {netip.a16} v2 v1     ; &a16
  v173 = OffPtr <*byte> [8] v22                     ; &a16[8]
  v542 = Bswap64 <uint64> v502                      ; bswap(input.addr.hi)
  v161 = Store <mem> {uint64} v22 v542 v23          ; a16[:8] = bswap(hi)
  v282 = Store <mem> {uint64} v173 v442 v161        ; a16[8:] = bswap(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
  v416 = Copy <uint64> v542                         ; bswap(input.addr.hi)
  v299 = Copy <uint64> v502                         ; output.addr.hi = input.addr.hi

If we remove the values not used to compute v299, we get this SSA form:

  v502 = ArgIntReg <uint64> {ip+0} [0] ; input.addr.hi
  v299 = Copy <uint64> v502            ; output.addr.hi = input.addr.hi

In practice

Most of these rules already exist in generic.rules. They use conditions to validate their context: ssa.IsSamePtr() for the same address, ssa.Disjoint() for addresses that do not overlap. The rule forwarding a stored value to a load already exists with three variants looking through several other stores. Here are the two we need:

(Load <t1> p1 (Store {t2} p2 x _))
    && ssa.IsSamePtr(p1, p2)
    && copyCompatibleType(t1, x.Type)
    && t1.Size() == t2.Size()
    => x
(Load <t1> p1 (Store {t2} p2 _ (Store {t3} p3 x _)))
    && ssa.IsSamePtr(p1, p3)
    && copyCompatibleType(t1, x.Type)
    && t1.Size() == t3.Size()
    && ssa.Disjoint(p3, t3, p2, t2)
    => x

Go 1.27 added the rule loading through a move with CL 748200 to fix issue #77720:

(Load <t1> op1:(OffPtr [o1] p1) move:(Move [n] p2 src mem))
    && o1 >= 0 && o1+t1.Size() <= n && ssa.IsSamePtr(p1, p2)
    && !ssa.IsVolatile(src)
    => @move.Block (Load <t1> (OffPtr <op1.Type> [o1] src) mem)

It lacks a variant without an offset:

(Load <t1> p1 move:(Move [n] p2 src mem))
    && p1.Op != ssaop.OpOffPtr
    && t1.Size() <= n && ssa.IsSamePtr(p1, p2)
    && !ssa.IsVolatile(src)
    => @move.Block (Load <t1> (OffPtr <p1.Type> [0] src) mem)

There is no generic rule to cancel two byte swaps, but the AMD64 lowering pass includes this rule:

(BSWAP(Q|L) (BSWAP(Q|L) p)) => p

After switching to Go’s development branch and adding the missing rule, the generated assembly code is worse than with Go 1.26.8, even though our additional rule slightly improves the situation at the end:

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
; Push the stack (16 bytes):
;    0(SP) a16 [16]byte
 PUSHQ   BP
 MOVQ    SP, BP
 SUBQ    $16, SP

 CMPQ    net/netip·z4(SB), CX       ; check "z" if this is an IPv4 address
 JNE     end                        ; if not, stop here

; The four forwarded bytes: the low half of input.addr.lo is taken apart and
; put back together in registers
 MOVQ    BX, DX                     ; DX = input.addr.lo
 SHRQ    $24, BX                    ; BX = input.addr.lo >> 24
 MOVQ    DX, SI                     ; SI = input.addr.lo
 SHRQ    $16, DX                    ; DX = input.addr.lo >> 16
 MOVQ    SI, DI                     ; DI = input.addr.lo, kept for the pack
 SHRQ    $8, SI                     ; SI = input.addr.lo >> 8
 MOVBLZX DIB, R8                    ; R8 = byte(input.addr.lo)
 MOVBLZX SIB, SI                    ; SI = byte(input.addr.lo >> 8)
 SHLQ    $8, SI
 ORQ     R8, SI                     ; SI = two low bytes of input.addr.lo
 MOVBLZX DL, DX                     ; DX = byte(input.addr.lo >> 16)
 SHLQ    $16, DX
 ORQ     SI, DX
 MOVBLZX BL, BX                     ; BX = byte(input.addr.lo >> 24)
 SHLQ    $24, BX
 ORQ     DX, BX                     ; BX = input.addr.lo & 0xffffffff

; Pack: byteorder.BEPutUint64(a16[:8], input.addr.hi)
;       byteorder.BEPutUint64(a16[8:], input.addr.lo)
 MOVBEQ  AX, net/netip·a16(SP)
 MOVBEQ  DI, net/netip·a16+8(SP)

; The four other bytes of input.addr.lo, read one by one from a16
 MOVBLZX net/netip·a16+11(SP), DX   ; a16[11]
 SHLQ    $32, DX
 ORQ     DX, BX
 MOVBLZX net/netip·a16+10(SP), DX   ; a16[10]
 SHLQ    $40, DX
 ORQ     DX, BX
 MOVBLZX net/netip·a16+9(SP), DX    ; a16[9]
 SHLQ    $48, DX
 ORQ     DX, BX
 MOVBLZX net/netip·a16+8(SP), DX    ; a16[8]
 SHLQ    $56, DX

; output.z = netip.z6noz
 MOVQ    net/netip·z6noz(SB), CX
; output.addr.hi = byteorder.BEUint64(a16[:8])
 MOVBEQ  net/netip·a16(SP), AX
; output.addr.lo assembled from the previous steps
 ORQ     DX, BX

end:
 LEAVEQ
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

The rule loading through a move, added in Go 1.27, introduced this regression.

Out of order

Let’s not give up now! In reality, the rewriting rules run before memcombine, notably in the late opt pass. At this point, the inlined versions of BEPutUint64() and BEUint64() still expand to sixteen byte stores and sixteen byte loads, matching their source code:

func BEUint64(b []byte) uint64 {
    _ = b[7] // bounds check hint to compiler; see golang.org/issue/14808
    return uint64(b[7]) | uint64(b[6])<<8 | uint64(b[5])<<16 | uint64(b[4])<<24 |
        uint64(b[3])<<32 | uint64(b[2])<<40 | uint64(b[1])<<48 | uint64(b[0])<<56
}

Let’s follow two bytes of output.addr.lo: addr[15] and addr[11]. Here is a simplified SSA form before late opt:

  v273 = Trunc64to8 <byte> v490                     ; byte(input.addr.lo)
  v226 = Trunc64to8 <byte> v225                     ; byte(input.addr.lo >> 32)
; […]
  v235 = Store <mem> {byte} v233 v226 v223          ; a16[11] = byte(lo >> 32)
  v247 = Store <mem> {byte} v245 v238 v235          ; a16[12] = …
  v259 = Store <mem> {byte} v257 v250 v247          ; a16[13] = …
  v271 = Store <mem> {byte} v269 v262 v259          ; a16[14] = …
  v282 = Store <mem> {byte} v280 v273 v271          ; a16[15] = byte(lo)
  v285 = LocalAddr <*[16]byte> {netip.addr} v2 v282 ; &addr
  v286 = Move <mem> {[16]byte} [16] v285 v22 v282   ; addr = a16
; […]
  v433 = OffPtr <*byte> [15] v285                   ; &addr[15]
  v435 = Load <byte> v433 v286                      ; addr[15]
  v479 = OffPtr <*byte> [11] v285                   ; &addr[11]
  v481 = Load <byte> v479 v286                      ; addr[11]

The first rule loads through the move: (Load (OffPtr [o] p) (Move p src mem)) => (Load (OffPtr [o] src) mem). It matches both loads, which now read a16 with the memory state before the copy:

  v600 = OffPtr <*byte> [15] v22 ; &a16[15]
  v435 = Load <byte> v600 v282   ; a16[15]
  v601 = OffPtr <*byte> [11] v22 ; &a16[11]
  v481 = Load <byte> v601 v282   ; a16[11]

The second rule shortcuts a load following a store: (Load p (Store p x _)) => x. It matches v435, as v282 stores a16[15]. It does not match v481: v235 stores a16[11] four stores earlier in the chain, while the variants of this rule look through three stores at most.

  v435 = Copy <byte> v273        ; byte(input.addr.lo)
  v601 = OffPtr <*byte> [11] v22 ; &a16[11]
  v481 = Load <byte> v601 v282   ; a16[11]

The same happens to the other bytes: the rule forwards the four bytes stored last, a16[12] to a16[15]. The twelve other loads now read a16 instead of addr.

BEUint64() becomes a chain of Or64, each one adding a byte shifted into place. memcombine is a pass written in Go, not a set of rewrite rules. It starts from the last Or64 of the chain and collects up to eight terms. If each term is a byte load, extended to 64 bits and shifted, and if the eight loads read consecutive addresses from the same pointer with the same memory state, it replaces the whole chain with a single 64-bit load and a byte swap. Otherwise, it tries again with four, then two terms, and from each intermediate Or64. Here is the loop checking each term in a simplified version of combineLoads():

for i := int64(0); i < n; i++ {
    v := a[i]
    shift := int64(0)
    if v.Op == shiftOp {
        v, shift = peelShift(v)
    }
    if v.Op != extOp {
        return false
    }
    load := v.Args[0]
    if load.Op != ssaop.OpLoad {
        return false
    }
    if load.Args[1] != mem {
        return false
    }
    p, off := splitPtr(load.Args[0])
    if p != base {
        return false
    }
    r[i] = LoadRecord{load: load, offset: off, shift: shift}
}

For output.addr.hi, the eight loads read a16 with the same memory state v282:

  v13  = Load <byte> v22 v282               ; a16[0]
  v530 = Load <byte> v14 v282               ; a16[1]
  v488 = Load <byte> v504 v282              ; a16[2]
  v405 = Load <byte> v537 v282              ; a16[3]
  v385 = Load <byte> v397 v282              ; a16[4]
  v361 = Load <byte> v373 v282              ; a16[5]
  v196 = Load <byte> v63 v282               ; a16[6]
  v432 = Load <byte> v315 v282              ; a16[7]
  v319 = ZeroExt8to64 <uint64> v432         ; uint64(a16[7])
  v329 = ZeroExt8to64 <uint64> v196         ; uint64(a16[6])
  v330 = Lsh64x64 <uint64> [true] v329 v138 ; uint64(a16[6]) << 8
  v331 = Or64 <uint64> v319 v330            ; a16[7] | a16[6] << 8
; […] same for a16[5] to a16[1]
  v401 = ZeroExt8to64 <uint64> v13          ; uint64(a16[0])
  v402 = Lsh64x64 <uint64> [true] v401 v55  ; uint64(a16[0]) << 56
  v403 = Or64 <uint64> v402 v391            ; | a16[0] << 56 = output.addr.hi

memcombine merges them into one load and a swap:

  v286 = Load <uint64> v22 v282   ; a16[:8]
  v285 = Bswap64 <uint64> v286    ; output.addr.hi

For output.addr.lo, here is the chain memcombine sees after late opt:

  v436 = ZeroExt8to64 <uint64> v273 ; addr[15], forwarded
  v448 = Or64 <uint64> v436 v447    ; | addr[14] << 8, forwarded
  v460 = Or64 <uint64> v459 v448    ; | addr[13] << 16, forwarded
  v472 = Or64 <uint64> v471 v460    ; | addr[12] << 24, forwarded
  v484 = Or64 <uint64> v483 v472    ; | a16[11] << 32, loaded
  v496 = Or64 <uint64> v495 v484    ; | a16[10] << 40, loaded
  v508 = Or64 <uint64> v507 v496    ; | a16[9] << 48, loaded
  v520 = Or64 <uint64> v519 v508    ; | a16[8] << 56, loaded

From v520, four of the eight terms are forwarded bytes, not loads from memory, and memcombine can’t combine them. It doesn’t merge the four remaining loads either, as they sit on top of the forwarded bytes.

Back in order

In summary, the rewriting rules run too early to be effective. A quick workaround exists: run an earlier round of memcombine before late opt. After this change, the generated code for the helper is back to the shortest possible version:

// AX = input.addr.hi, BX = input.addr.lo, CX = input.z
 CMPQ    net/netip·z4(SB), CX     ; check "z" if this is an IPv4 address
 JNE     end                      ; if not, stop here
 MOVQ    net/netip·z6noz(SB), CX  ; CX = netip.z6noz
end:
 RET
// return value = Addr{hi: AX, lo: BX, z: CX}

And the benchmark confirms it! ✌️

goos: linux
goarch: amd64
pkg: github.com/vincentbernat/go-netip-addrto6
cpu: AMD Ryzen 5 5600X 6-Core Processor
                   │   Go 1.26.8    │             Our branch              │
                   │     sec/op     │    sec/op     vs base               │
AddrTo6/safe          6.5470n ±  0%   0.8944n ± 4%  -86.34% (p=0.002 n=6)
AddrTo6/unsafe        0.9071n ±  3%   0.8682n ± 1%   -4.28% (p=0.002 n=6)
AddrTo6/builtin       0.8871n ±  2%   0.8785n ± 1%        ~ (p=0.310 n=6)

Next steps

I think Go maintainers would reject this change because of the additional memcombine pass. Instead, I plan to publish this blog post and bring up the subject again as a follow-up to issue #54365. Either the sheer complexity and the Go 1.27 regression convince the maintainers that adding a To6() method is simpler and more efficient, or they advise me on how to move forward. Either way, digging into this subject taught me a lot about the Go compiler! ⚙️

Update (2026-10)

I opened issue #81994 to propose Addr.To6(). Give it a 👍 if you want it in Go!

IPv4-mapped IPv6 addresses let you handle only IPv6 addresses in your code and keep conversions at a few well-defined boundaries. I use them in Akvorado. ↩
This is not strictly equivalent. The zero value becomes :: while it would make more sense to leave it untouched. ↩
To avoid catastrophic bugs when netip.Addr’s layout changes, you must add tests to detect it. This is more dangerous if you put this code in a package. Either ask users to run the tests themselves, or detect the change at run time and panic. Hiding this optimization behind a build tag would make users aware of this potential trap. ↩
I produced the assembly code with GOTOOLCHAIN=go1.26.8 GOAMD64=v3 ./go-asm '\.asm' from the companion repository, then edited it a bit to keep this article from turning into an endless rabbit hole. Due to an unfortunate sequence of events, we switch between versions: Go 1.27 introduced a regression that blurs the point of this article. ↩
The function is short enough for the compiler to inline it, so the assembly code may vary depending on the surrounding code. ↩
MOVBEQ requires GOAMD64=v3, matching the x86-64-v3 microarchitecture from 2013. Otherwise, the compiler translates BEPutUint64() to BSWAPQ+MOVQ and BEUint64() to MOVQ+BSWAPQ. ↩
When the call is used as a statement, a struct literal alone is invalid. The patch then turns it into _ = netip.Addr{…}. ↩

The compiler can also write an HTML file with the result of each pass:

$ GOSSAFUNC=AddrTo6Safe \
> GOTOOLCHAIN=go1.26.8 \
> GOAMD64=v3 go build -a .
dumped SSA for AddrTo6Safe,1 to ./ssa.html

↩

Source line numbers in parentheses follow value identifiers, but I removed them from the examples. The SSA form also features branches, but we don’t need them to understand our optimizations. ↩

This is the first half of the third part (I, II) of our long-delayed series looking at Hearts of Iron IV, Paradox Interactive’s World War II grand strategy game, easily one of the most popular historical games on the market today and thus tremendously influential in both the popular history and gaming spaces.

Over the last two parts, we took a look at the military simulation that sits at the heart of Hearts of Iron, a division-level operational simulation of World War II, along with the doctrinal framework that contextualizes what is actually happening as divisions collide along the game’s front lines. While the doctrinal system struggles to really accurately represent the different ways that armies attempted to fight in the Second World War, the overall operational simulator is a remarkable achievement. Alas, the discussion is going to turn somewhat more critical from here as we move from the operational focus of the game – where the bulk of developer time and attention have gone – to the ‘everything else’ of the game, where simplifications and streamlining often go awry.

In this part, we’re going to move upwards to the strategic level, beginning with the question of politics, particularly domestic politics. Hearts of Iron IV has an understandably more simplified approach to politics than games like Victoria II or III or even Europa Universalis V which are substantially focused on questions of how changing conditions alter the political and economic balance of a polity. Simplified, however, does not mean absent: Hearts of Iron IV does have a ‘theory of history’ when it comes to the politics of the period.

Unfortunately – and I will not bury the lede here – Hearts of Iron IV‘s simplified politics serve to present an essentially authoritarian vision of politics in which the opinion of the people matters essentially not at all, where state power can easily and effortlessly shape outcomes and where authoritarian central direction is easy, frictionless and never produces unintended results and where democracy comes effectively only with drawbacks. It is a vision of politics that begs the question¹ in favor of empire and autocracy, where the only way to achieve social, cultural or political change is to first have control of the state. Governments in Hearts of Iron do not fall, they cannot be overthrown, they can only decide to abolish themselves, so absolute is authoritarian state power.

It is thus not inaccurate to say that Hearts of Iron IV‘s political model, as a result of careless simplification is fascist, in that it assumes that all politics flows down from the state, dictated by the leader and merely accepted by the people who do not exist as individuals, but merely units of state power. I do not think that the developers set out to build a fascist model of politics (indeed, I know they didn’t), but alas, despite themselves, in an effort to get the player ‘to the action’ with as little friction as possible, they have done so.

But first, if you like what you are reading here, please share it, as I rely on word of mouth to replenish my manpower pool after poorly considered post topics. If you really like it, you can support me, my academic work and my public writing, including this project on Patreon! I can’t promise to use your support to buy a division worth of tanks, but I also will not promise not to do that. If you want updates whenever a new post appears or want to hear my more bite-sized musings on history, security affairs and current events, you can follow me on Bluesky (@bretdevereaux.bsky.social). I am also active on Threads (bretdevereaux) and maintain a de minimis presence on Twitter (@bretdevereaux).

Picking up in our United Kingdom game where we left off last time – with Japan entering the war – two major naval battles in October and November in the Strait of Malacca largely confirmed that my ‘fast squadron’ of carriers and battlecruisers could control the strait, handing the IJN a series of nasty batterings that cost them a few capital ships and substantial damage to a number of others.
The Dutch still managed to lose Java, but control of this area let me steadily work with a modest army to take Siam out of the war, then reclaim Dutch Indonesia and Borneo. Meanwhile, mounting IJN losses meant that the USA was actually able to support the Philippines, so by January of 1942, the war in the Pacific had already decisively shifted away from Japan.
I made the decision to remain focused on Europe, because the AI United States would have no problem defeating Japan at this point, so I kept my fleet operating in Indonesia to keep that area secure while the IJN was steadily dismantled by the USN.

Politics

On the surface, Hearts of Iron IV appears to have the components of an interesting political simulation: each country has a governing ideology along with a pie-chart of what ideologies are popular with the populace, along with stability (representing how stable the government is) and war support (reflecting how committed the populace is to the war). The problem is two-fold: none of these mechanics are very developed and none of these mechanics interact meaningfully with each other.

The system, such as it is, begins with ideology and here we run into immediate problems in representing the actual political conditions inside of most countries in the period. There are just four ideologies: democratic, communist, fascist and non-aligned. While the game does have ‘sub-ideologies’ (for instance, ‘liberalism,’ ‘conservatism,’ ‘socialism’ and ‘populism’ for democracy) these have functionally no influence on gameplay – their sum effect is to determine if your ‘same ideology’ diplomatic opinion bonus is +20 or merely +10, both numbers which in actual gameplay are either indistinguishable from zero or indistinguishable from 100, depending on what you are trying to do.² So in practice, there are just the four ideologies.

These ideologies do matter, because the governing ideology of a country determines what actions it can take, although in practice this is just an exciting set of disabilities applied to democracies. Democracies are heavily limited in the actions they can take, particularly not being able to declare war without meeting specific conditions, with requirements that ‘world tension’ (the amount of conflict in the game) reach certain levels before they can take actions. Democracies that guarantee the independent of other countries lower world tension, which in the game mechanically is bad for them, because democracies have a lot more things (like conscription and mobilization laws) gated behind world tension. Communist, non-aligned and fascist governments largely lack these limitations and thus have much greater freedom of action to mobilize earlier (which, as we’ll see in a later post, is simply better rather than being a truly strategic choice) and attack more freely.

The idea here is to model the challenge of bringing the United States and United Kingdom onto a war footing before the war began but in practice, mechanically, democracy is simply a weaker form of government in Hearts of Iron. It is striking that no effort is made to simulate the strengths that democratic governments displayed in this period, particularly in adaptability and economic mobilization. Historically, the United Kingdom, a fraction of the size of Hitler’s continental European empire after 1940, nevertheless outproduced it in key categories like aircraft.³

The game tracks the popularity of specific ideologies in a given country with a pie-chart, but the insufficiency of this model becomes fairly obvious fairly quickly. While each country often has a unique name for each ideology, representing actual political parties in the period, divisions within an ideology are not represented. So, for instance, the United States is represented as having 99% popular ‘Democratic’ ideology. The idea here is that in Hearts of Iron IV‘s really simplified politics, the Republican and Democratic parties of 1936 are indistinguishable – both ‘Democratic’ ideology parties – and so are combined (though this is still too high – Socialist third-party candidates generally got ~2-3% in the federal elections of this period). It also strikes me as wrong – the fact that Strom Thurmond leading a ‘State’s Rights’ party (a segregationist party that probably ought to be classified at least as non-aligned given its intent to restrict the franchise) would go on to win four states in 1948 (within the game’s timeframe!) suggests that there was a meaningful constituency for a less democratic United States even in the 1940s.

A smattering of the political screens of major powers at the 1936 start. As you can see, there is quite a bit of political compression going on here, particularly with the United States and the United Kingdom. But equally the perfect information and precise figures for the political leanings of authoritarian countries are odd – how would anyone **know** what percentage of Russians, Italians or Germans truly supported the ideology of the regime, given that not doing so was a reliable way to get killed?

Other countries suffer the same ‘party compression.’ The game has no way to distinguish in the UK between the Tories and Labour, so it doesn’t: they’re merged into a Tory (Democracy Ideology) mega-party with an unshakeable lock on politics. Pre-war Germany’s situation in 1936 are likewise simplified: the Nazi party starts with 50% popular support, while there is a chunk of Democratic ideological support (marked as Zentrum, despite the fact that the party had dissolved itself under Nazi pressure in July of 1933), communist support (the KPD) and some non-aligned. The SPD/Sopade isn’t represented at all.

Meanwhile, there is the absolute mess of the ‘non-aligned’ ideology, which encompasses non-fascist despotism, traditional absolute monarchy, quasi-democratic oligarchies, colonial dependencies and even the fractured, military-dominated political structure of the Japanese Empire. It is difficult to avoid the conclusion that the ‘non-aligned’ category functions as effectively a ‘grab bag’ for every country that doesn’t fit into the first three categories. In practice, the game thus largely treats ‘non-aligned’ as thus an absence of ideology: there is no way to start a global ‘non-aligned’ movement the way that democracies, fascists and communists can all create (or start with) factions aimed at promoting their ideology.

The result is a political system that simply lacks the granularity to represent politics as they existed in many countries in the period, which as we’ll see, mostly doesn’t matter for the game because this system barely matters for political change compared to the much greater influence of the focus system and political advisors. The game does have mechanics for elections, but in most of the major democracies, with all of the pro-democracy parties fused, that doesn’t mean much.

Popular ideology can change over the course of the game, but this too is extremely simplified. In practice, most countries have access to advisors they can hire (at the cost of 150 political power) who will cause popular opinion to trend towards one ideology at a rate of 0.10% per day. For some countries, getting this advisor requires completing a few national focuses (see below) to get on the right track for an ideology switch. But I want to stress how big that rate is: at +0.1 per day (the standard rate for the ‘Communist Revolutionary, Fascist Demagogue, Democratic Reformer and Staunch Monarchist advisors) a country could go from having no support at all for a given kind of government to having enough support (50%) to transition to that entirely new kind of government with little to no issues at all in less than a year and a half.

You just have to hire the right one guy. Also, this requires a government to decide to hire an advisor whose entire purpose is to undermine the government, overthrow it and in many cases presumably murder every other member of the government, but we’ll come back to that.

A similar lack of consequence assails stability and war-support as mechanics. Both stats offer bonuses when above 50% and penalties below 50% and in theory low war support can feed back into low stability which can in theory feed back into creating a political crisis. In practice, this almost never happens. War support acts as a more-or-less fixed value (it isn’t meaningfully responsive to casualties) which can be raised through war propaganda (costing political power, see below), while stability is likewise generally a fairly static value. Generally, the internal politics of states in Hearts of Iron IV are extremely stable such that the player needs to actively intervene to force political crises (sometimes a tool to intentionally change governing ideology early).

Our United Kingdom campaign comes with several examples of this sort of a-historical stability. The game requires, for instance, a bespoke event to transition from Neville Chamberlain’s government to that of Winston Churchill because the political system is both not granular enough to model the Norway Debate and subsequent vote of confidence happening as a debate within a political ideology as a result of serious policy setbacks.

Likewise, somewhat famously, support in the Wehrmacht for the invasion of France in 1940 was tepid and a number of high ranking officers were on the verge of attempting a coup if the invasion of France had failed. Of course, historically it succeeded, cementing Hitler’s power through to the end of the war. But Hearts of Iron IV has no way to model the failure of Fall Gelb (the invasion of the Low Countries) as a political event which might imperil the Nazi regime. Instead, unless the player is actively and aggressively attempting to intervene in internal German politics in ahistorical ways, Germany remains fully committed to Hitler’s vision down to the end of the war.

Instead, the political system serves as an essentially minimal scaffolding necessary to produce what Hearts of Iron IV actually cares about: the operational simulation. This is perhaps most obvious in the choice of political advisors and military staff, representing essentially key figures in something like a cabinet and a general staff respectively. But while these advisors are named after historical figures (with portraits), they are for the most part just a set of standard bonuses the player is choosing between in preparation for the operational simulator. Any sense that these choices might be dictated by domestic politics is removed by the fact that these slots always (I am unaware of any exceptions) begin empty, so that assembling a collection of advisors – really a collection of advisor-themed bonuses – is a key expenditure of political power in getting ready for the war during the 1930s.

But apart from advisors whose only specific purpose is to promote a specific ideology (which you only choose if you intend to ideology switch to that ideology, there isn’t any need to ‘defend’ the popularity of your current governing ideology because of how static the political model is here), these ‘advisors’ do not interact with your domestic political situation at all.

This is, however, in stark contrast to the thing that does matter quite a lot.

On Focus

Part of the reason the political mechanics remain largely skeletal is that for the most part core player political decision-making doesn’t take place there: it takes place in the focus tree.

Via the Wiki, this is a zoomed out view of the entire focus tree for the United Kingdom. It is, compared to other major powers, a relatively small focus tree – the major democracies (UK, USA, France) have gotten generally fairly little in the way of new content for quite some time (put a pin in that) and as a result tend to have relatively minimal – as such things go – focus trees.

Every country in Hearts of Iron IV has a focus tree and nearly all of them are unique. This is a significant change from HoI4‘s structure on release, where only a handful of countries (the major powers) had unique focus trees, while every other country has a ‘default’ focus tree. However, years of updates and DLCs have added bespoke focus trees to nearly every country on the map, with the result that only a handful of small countries use that ‘default’ focus tree. Some countries, however, still have far more developed focus trees than others, which gives a good sense of where the developers expect most players to spend their time (unsurprisingly, major players like the USSR, Germany, Japan all have very expensive trees; the trees for the USA and the UK are more developed than for most minors but also very obviously not at the same level as those for the other major powers – an implication we’ll come back to when we discussing modding).

Each node on the focus tree (a ‘national focus’) represents a specific political decision meant to represent a choice to focus the government on a specific aim for a short period (generally 70 days). These are arranged in a series of ‘trees’ where earlier foci unlock the ability to choose later ones and where branches are frequently mutually exclusive, forcing the player to choose a political direction which may then last over several foci. Most foci are fairly direct, offering some sort of bonus (easier research in a field, some new factories, a small permanent bonus called a ‘national spirit’) once completed, but most countries have a part of their focus tree designed to allow them to switch governing ideology through a series of foci that empower a specific different ideology, and many countries also have foci that unlock casus bellorum enabling them to go to war where they might not otherwise be able to do so.⁴

So in practice, each country begins the game by selecting a focus of the few available at the top of tree. This triggers a timer (typically 70 days, but many shorter 35-day foci exist, particularly in recently updated trees) after which the focus is completed, the country gets the bonus and a new focus is selected, with a few new choices opened up in the tree by the completion of the first focus and so on.

Enacting a focus is not entirely free. The game attempts to simulate the ‘political capital’ that a government has through a political power currency, which most countries generate at a rate of 2 per day.⁵ This currency is used to hire new advisors and to change a country’s laws (most notably conscription and economic mobilization laws) and is usually in short supply, particularly in the early game. Enacting a focus costs 1 political power per day (representing the governments efforts to get the job done), so most foci cost 70 political power, which is about half of what most advisors or law changes cost.

That said, national foci are powerful enough that it is fairly rare that any player would want to ignore them for the political power cost (except, rarely, right before a war is about to start, where a player wants to stockpile political power to be able to rapidly shift to stronger mobilization and conscription laws). Instead, the tendency is to have a focus running continuously well into the mid-game, making the key decisions here what focuses to take and in what order.

The range of what national focuses can do is unsurprisingly vast, but there is a common structure, generally. Most countries have a branch of the tree devoted to developing industry, which offers bonus civilian and military factories, extra building slots and research bonuses for that sort of thing, alongside a branch that instead focuses on military development, often unlocking research bonuses for specific kinds of units and national spirits that offer country-specific bonuses to production or combat. For countries that historically had active air or naval arms, this part of the tree is often split into non-mutually exclusive branches between the services, forcing the player to prioritize what part of their military to focus on first.

Then there is generally a series of ‘political paths,’ which often encompass together both domestic and foreign policy. Typically at the top of these trees is the crucial decision to either remain the ideology the country starts as or to attempt to shift ideology, with various ideology shifts having a series of foci which often empower that ideology. Indeed, and this seems worth noting, in a lot of cases, these foci exert a substantially stronger ideological push on a country’s population than most other options the player has, either by unlocking specific ticking modifiers or by unlocking specific decisions (often culminating in a civil war in which the player can, by winning, force the ideology switch). Generally tucked into the political path are also a set of foreign policy choices, usually to include focuses that result in allying with countries of similar ideologies or – for more expansionist ideologies (which is to say not the democratic ones) – foci that offer war goals against various countries to enable military expansion.

The political focus tree path for the United Kingdom, which makes up about half of their focus tree. As is typical, there are clearly delineated focus paths for taking Britain fascist, communist or non-aligned.

The result of all of this is that the key big picture decisions are not made in the political system itself, but rather in the focus system. If the player wants to, say, take Britain non-aligned they do so not by really engaging deeply with the political system, but by selecting the non-aligned focus path, which actually has a focus that starts popular opinion moving non-aligned. This creates something of an oddity because under normal circumstances, the player is clearly positioned as the government, but a player who intends to ideology shift is plotting against their government. In essence, Hearts of Iron IV imagines that the way a county shifts ideologies is that the existing government opts to spend precious political capital undermining itself in order to prepare the war for a civil war it intends to lose.

A partial image of Germany’s political paths.
You may notice that Germany’s focus tree is **so vast** that it requires a handy navigation aid in the lower left to allow the player to quickly jump to each branch, something not present for the much smaller focus trees for Britain, France, the USSR or the United States (Japan, China and oddly, the British Raj, also have extremely large focus trees with navigator panels). **This might suggest something** about where the Hearts of Iron team is spending its resources and what they understand about their playerbase.

We’ve seen this problem before, where Paradox titles struggle to decide if the player plays as a government or as the disembodied ‘spirit’ of a state, but of course the idea that nations have spirits at all is a loaded, contested one, bound up with nationalist notions of ‘national destiny.’ Notably, however, the player is very clearly not an expression of the actual public will: at no point is the player actually constrained to follow the popular ideology: it is only the ruling ideology that constrains them. The people and their ideology are, in Hearts of Iron IV for the most part just clay, eager and ready to be molded by the player’s simple decision to click this button and not that one.

And to be clear I think it isn’t too hard to understand why the game has been designed this way: if the core of the Hearts of Iron experience is the operational simulation, then everything else is simply a frame to get the player to that simulation. But of course for the most popular grand strategy game – which is the genre label Paradox prefers for its games – that is a troubling framework because it greatly simplifies the strategic and political layer.

Meme Politics

To explain how, I am going to borrow a term from Samantha Hancox-Li, who called Hearts of Iron IV‘s approach meme politics. Hancox-Li defines the idea of ‘meme politics’ as consisting of three conjoined political assumptions:

Every policy does exactly what it intends
Politics is straight forward and information is perfect
Policy does not face meaningful resistance

And I think that is a relatively fair description of the focus tree system’s approach to politics. Each focus declares, right on the tin, exactly what it will do and these choices never go awry – even the foci that can cause a civil war will have that clearly declared in their descriptions in advance. I find this particularly striking when it comes to industrial policy: just about every country has an industrial policy section of the focus tree, where in most cases they are merely selecting the “I would like more civilian and/or military factories 35 or 70 days from now” focus and letting it run.

But of course in practice in the real world, industrial policy is remarkably difficult and very frequently goes wrong: government interventions often lead to reduplicated efforts, sectors bloated beyond requirements, or they simply fail. Even a casual read of something like Adam Tooze’s The Wages of Destruction: The Making and Breaking of the Nazi Economy (2006) reveals how much of a confused muddle Nazi industrial policy was. Allied armaments and economic efforts fared better, but were still often chaotic and impromptu at the time – initial US estimates of the military production possible in 1942, for instance, were wildly over-optimistic – akin to a situation where the ‘build military factory’ focus says it will add ten military factories but only adds five (or none!). But that simply cannot happen in Hearts of Iron IV.

Likewise, there is rarely much meaningful pushback for these focuses: they do what they say they do and only very few carry the possibility of blowback (which is – again, perfect information – clearly marked). An industrial plan never unexpectedly runs up against resistance from industrialists or workers or farmers or foreign financial interests. If you are playing as Communist China, you just trigger the ‘Agricultural Reform’ focus and ‘The Great Production Movement’ which just directly give you bonuses to construction speed and production because no industrial modernization movement led by Mao Zedong ever went wrong due to incomplete information, faulty implementation or any problem of unfounded ideological assumptions.

This lack of blowback is, of course, most obvious in the domestic political branches of the trees. While in many cases switching governing ideology does require a civil war or comes with penalties to stability, in practice making the decision for the government to abolish itself is as simple as clicking on the focus button, at which point the whole machinery of government – represented by the political power you are spending – gets to work on the job of becoming a different kind of government and unless that effort triggers an explicit civil war, no one tries to stop you.

Likewise, so long as you do not trigger one of those ideology-shifting trees, government control is extremely stable. In practice, throughout the war, leaders were abundantly aware that their power might be fragile – that battlefield setbacks or other problems might compromise their ability to lead. Not so in Hearts of Iron IV: governments are only fragile when they choose to be.

It is equally striking that in a game simulating an era of mass politics, the people matter very little to this system. As noted above, radically changing the population’s political beliefs in HoI4 is not hard – it is, in fact, very easy: it costs 150 political power to hire the single advisor who on their own will change a majority of the minds in the country in less than two years. 150 political power is, again, just about twice the cost of a single national focus or the same cost as moving a country’s conscription or mobilization law by a single step. This is a model of politics where once a political faction gets into government, mass-converting the entire populace and country to their ideology is presented as easy, a process of simply hitting the right button.

My run settled down into a fairly stable situation for most of early 1942. With no decision in the West, AI Germany did not declare war on the USSR and indeed the USSR is not going to join the war at all in this run. That left the entire German army on the western front, which required a longer build-up for me to have a viable breakthrough force.
That said, by May, 1942 I had assembled a mobile force of 10 armored divisions and 10 supporting motorized divisions to attempt to ‘punch outwards’ and launched that offensive in June. The initial goal was to push out eastward from Utrecht and then use the relatively flat ground to run to the Weser before turning north to trap any Germany forces left in the northern Netherlands.

Imperialism by Focus

When I was planning this series, I knew I’d want an example of just how absurd the outcomes that the focus tree can almost effortlessly give you are. Since we’re doing a United Kingdom run in the background, I thought I would use the Imperial Federation decision-chain as an example.

Now the concept of something like an Imperial Federation is not entirely a-historic – like many of these ‘alternate history’ paths, it is based on an idea that was talked about in the period – although as equally frequent the case, an idea that never got very far. From 1887 to 1937, the British Empire held somewhat regular ‘Imperial Conferences,’ where representatives of the constituent elements of the British Empire, including the Dominions, would meet. One of the ideas floated in the late 1880s and very early in the 1900s was the idea of creating a federal superstate encompassing the United Kingdom and the Dominions, an Imperial Federation; the idea never had tremendous support and was basically dead by 1926. But the United Kingdom focus tree lets you revive the concept and – solely as the United Kingdom, by pure force of political will (by which we mean pressing the button) force it through.

The entire sequence requires 12 national focuses, involving investments (fairly modest in scope and which come at no cost except the 70 day delay and political power cost of a focus) in the industry of India and the Dominions and then holding an Imperial Conference.

The focus tree path to get to the Imperial Conference. The India branch is optional if the player does not intend to include India in the resulting federation.

That then fires an event, the ‘Imperial Conference,’ at which the player can propose various common economic, military and political policies, at which point they can then propose an Imperial Federation. If all of the Dominions (potentially and the British Raj) accept, all of them get massive negative ticking autonomy, causing them to drift inexorably deeper under British control until the final Imperial Federation focus becomes available, annexing Canada, Australia, New Zealand, South Africa and the British Raj into a single mega-state, the Commonwealth of Nations, which contrary to its name does not in any way function as a federal state, but rather as a single, unitary state of enormous size.⁶

Now it is possible for the Dominions to refuse – as they absolutely would have if this had been proposed in this period – but by raising their diplomatic opinion to +100, the player can guarantee a 100% acceptance rate. And – more meme politics – raising diplomatic opinion to 100 is simply a matter of clicking the ‘improve relations’ button, which will cost 10 political power to start (so almost nothing) and a ticking cost of 0.2 per day⁷ will raise relations to +100 in just a couple of months. Want to get the Canadians to like you so much they’d give up self-government for you? Just hit the button.

The result is that in practice it takes a player-run United Kingdom just about two years to achieve something that in practice in the 1930s and 1940s was probably impossible at any level of effort. The popular consciousness of entire countries is effortlessly molded, are a perfectly linear rate of x% per day, into whatever form is required.

Notably, the game also does not ask the player to think at all about the outcome of this decision, it just works. And here I think a brief thought experiment is useful: what would an Imperial Federation c. 1940 entail? Decisions would have to be made about how the Dominions would be represented in a ‘super-parliament’ in London: by population? By white population (think hard about South Africa’s situation before answering)? And what about the Raj? If India was represented by population, it would instantly hold 70% or more of the seats. Now it is hard to see how India and Pakistan – with the Indian independence movement already very well advanced (the Non-cooperation Movement started in 1919!) – would ever agree to any such federation but surely they would not agree to any federation where they had an artificially reduced percentage of the vote. But it is equally impossible to imagine the United Kingdom or the Dominions agreeing to a super-federation that would have been, in practice, the Empire of New Delhi given the balance of votes in a pure by-population-system.

In short, even if India isn’t included, there are just very obvious insurmountable political hurdles here both for actually forming the federation and also that such a federation would immediately face after the war. Including India merely compounds those problems.

Hearts of Iron IV asks the player to consider exactly none of these issues. You simply march linearly down the focus tree, spending political power when necessary, remember to use ‘improve relations’ two to three months before firing the Imperial Conference decision and there you go. The focus to accomplish a probably impossible feat does exactly what it says on the tin, with no pushback and perfect information about the results and the effort requires the whole way through. The problems all, presumably, work themselves out off-screen: a good example of Hearts of Iron IV‘s ‘meme politics’ structure, but hardly a unique one – basically all political questions in HoI4 are resolved this way.

And the wild part is, the Imperial Federation is one of the most complex of such sequences, since it requires a whole event chain and a substantial delay between getting everyone to agree and having the federation actually happen (though mechanically, once everyone agrees, no one can really stop the federation from happening – the downward ticking autonomy is more than anyone is likely to be able to counteract). You hit the right button, wait for the delay and the thing the button says it does happens and the opinions or resistance of the hundreds of millions of people who are involved doesn’t matter a damn.

And here we can see just a few days later, my offensive has broken into the open and made it to the Weser (and even over it, stealing a march by getting into Bremen before serious opposition could dig in) with the result that roughly 40 German and Italian divisions ended up trapped in a pocket between Leewarden and Wilhelmshaven. While they have ports, my naval presence in the German Bight is sufficient that no supplies are getting through and no one is leaving either.
On the southern end of the pocket, I make it to Dortmund but not deeper into the Rhineland as the terrain there is difficult and the attack runs out of steam before I can secure all of the urban centers. That’s fine – this rush is plenty for now.

The Effect

This is obviously an extremely simplistic model of politics. The contrast with the still-quite-simplified but far more complex political simulation involves in Victoria II or III or Europa Universalis V or Crusader Kings III is remarkable. As Hancox-Li notes, this is a vision of politics which seems to have crept out of gaming spaces into the real world (sometimes more or less explicitly invoked) – an assumption that major changes in society are not difficult or fraught or complex or sometimes backfire, but merely require finding the right button, the right national focus, which is neatly labeled “Do The Thing” on the tin, and pressing it forcefully enough.

And it isn’t hard to see, as a question of development time and focus, how we got here: this is a game about fighting World War II, fundamentally focused on its operational simulation. Everything else – diplomacy, politics, espionage, industrial policy⁸ – is merely a delivery mechanism, the unadorned, simple frame in which to present the operational painting. And so choices can be simplified down to the basics, made predictable and streamlined so they do not distract the player too much from the core of the game, which is smashing divisions into other divisions. Equally, most of the friction here is removed to facilitate players who want to change up the exact layout of the board where they are smashing their Army Men together.

And to be clear, I have nothing against a pure operational simulation or war games in general. But this is, notionally, supposed to be a grand strategy game. Grand strategy is, definitionally, the coordination of political, diplomatic, economic and military means to achieve strategic ends. If two (three, really, as we’ll see) of those means are radically simplified in this way, are we really doing grand strategy? And if we’re not – why include the strategic simulation at all? Why not structure the game as a series of operations?

But there is, I think a deeper problem here (one we’ll see recur over the next few posts), the unintended implications of these gameplay simplifications. And I’ll be blunt: Hearts of Iron IV presents an authoritarian model of politics. It presents a world in which the authoritarians (both fascists and the communists) are fundamentally right about the nature of politics – that individuals do not matter. All that matters is the state, embodied in the player.

The people in Hearts of Iron IV do not yearn for freedom, nor do they really even have their own ideologies at all. All it takes is hiring the right propagandist and selecting the right focus tree button – decisions whose cost and time investment are trivial compared to the military aspects of the game – and any leader can bend any population into believing anything. In HoI4, the authoritarian, central direction of all of society – culture and economy – is not merely possible, but it is desirable, it is better mechanically, as players will find that authoritarian government forms allow them to adopt better (for military activity, the only thing the game considers) laws earlier, to be more assertive strategically, all while suffering no penalties at all from the effort to centrally direct an entire society. Playing as a democracy in Hearts of Iron IV is essentially a ‘roleplay’ choice to accept limited mechanics for no real benefit.

This stands, of course, in rather direct and remarkable opposition to the actual war in which many of the advantages of democratic forms of government were on display, particularly in the organization and employment of economic resources. The Soviet economic mobilization during the war (conducted in the context of extreme military pressure and lost territory) was undeniably impressive, a feat of will and sacrifice, yet in 1942 and 1943, the United Kingdom – not the British Empire, just the United Kingdom – was outproducing the USSR in total GDP despite having a tiny fraction of the landmass and around a third of the population.⁹

If anything, the advantages that open, democratic societies could bring to war was even more obvious when it came to research and technological development. The consistency with which the United States and the United Kingdom deployed new technologies first and with greater effectiveness is staggering: radar, sonar (=ASDIC), proximity fuses, industrial technology, superior cryptography, advanced gunsights and stabilizers, new explosives (like Torpex) and of course nuclear weapons. And whereas most powers in the war were forced to specialize on particular classes of military equipment (e.g. Japanese tank designs were outdated, the USSR’s navy was very limited, Germany lacked effective heavy bombers, etc.) the United States and United Kingdom did all of that while also designing competitive equipment models in effectively every category. It is a staggering triumph of intellectual-industrial might that goes almost entirely unsimulated in Hearts of Iron.¹⁰

Likewise, the strategic downsides of autocracy – particularly the tendency of autocratic leaders to order foolish, wasteful military actions out of arrogance, ignorance and pride – were abundantly on display in the Second World War for both the Axis and the USSR, but this too is unrepresented in the game.

Fundamentally, Hearts of Iron IV has a political model where all that is required to change the kind of society one has is to seize power and then order the Gleichschaltung¹¹ from above. That is a fundamentally authoritarian view of power and also a fundamentally contested view: part of what the war was about was, on some level, if this view of politics was sustainable, if polities organized on this basis could compete with the liberal democracies and by and large the verdict of the battlefield¹² was no, they could not. Hearts of Iron IV grants the question, a priori, to the authoritarians, as an act of uncritical game design: authoritarian politics – fascist politics – work in HoI4 in exactly the way that the fascists of the 1930s and 1940s imagined they did.

In an effort to streamline away any political friction and get straight to the ‘fun stuff’ of war, Hearts of Iron IV adopts a fundamentally authoritarian vision of politics, uncritically and without caveats.

And the resulting vision is simply inaccurate. To take our Imperial Federation example above, in the real world the rising tide of decolonization could not simply be wished away – not even in the 1930s – by hiring the right advisor or pressing the right button. Popular opinion was not, in fact, easily and effortlessly molded by governments, but in fact would spend the 20th century for the most part bending governments rather than being bent by them. World War II was a war of mass politics in which the politics of the masses mattered a great deal and the decision by HoI4 to simplify that away into an exercise of pure state power leaves the player with quite a misleading assumption of how the politics of the 1930s came to be the way they were.

One understands the desire to simplify the mechanics that frame the core experience of a game, but it is necessary to be very careful in how those elements are simplified so that the simplification doesn’t end up doing violence to the underlying history.

Unfortunately, domestic politics is hardly the only historical concern of the 1930s and 1940s that Hearts of Iron IV airbrushes away – next week we’ll turn to the questions of occupation, bombing and war crimes. It isn’t going to get better.