← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Models/PlayerColor.swift (11717B)

1import SwiftUI
2
3/// A player's chosen highlight colour. Each player picks one of these so that
4/// — once collaborative play is wired up — both players' selections can be
5/// shown side-by-side without ambiguity.
6struct PlayerColor: Sendable, Identifiable, Hashable {
7    let id: String
8    let name: String
9    let tint: Color
10
11    /// The colour's *intended* position on the hue wheel, in degrees `0..<360`.
12    /// Hand-assigned rather than derived from `tint` so it stays a pure value
13    /// (resolving a SwiftUI `Color` to RGB needs a trait environment). Used
14    /// only by `assignedColor` to keep a participant clear of colours that are
15    /// perceptually similar to one already taken — not just exact matches.
16    let hue: Double
17
18    /// Opacity used when this player's cell is the active selection.
19    var selectedOpacity: Double { 0.70 }
20
21    /// Opacity used for the rest of this player's active word.
22    var highlightedOpacity: Double { 0.40 }
23
24    /// Opacity used for faint author-attribution tinting.
25    static let authorTintOpacity = 0.16
26
27    /// Fill for UI tied to this player's active selection (the selected cell).
28    var selectionFill: Color { tint.opacity(selectedOpacity) }
29
30    /// Fill for UI tied to this player's passive highlight — the rest of the
31    /// active word.
32    var highlightFill: Color { tint.opacity(highlightedOpacity) }
33
34    /// Fill for UI tied to faint author-attribution tinting.
35    var authorTintFill: Color { tint.opacity(Self.authorTintOpacity) }
36
37    /// Background wash for the clue bar. The clue bar composites over the
38    /// system background, so unlike the always-white grid cells the wash's
39    /// perceived colour depends on the appearance: at the faint author-tint
40    /// opacity over a near-black Dark Mode background the hue reads as black.
41    /// Raise the opacity in Dark Mode so the player's colour stays visible.
42    func clueBarFill(dark: Bool) -> Color {
43        tint.opacity(dark ? 0.20 : Self.authorTintOpacity)
44    }
45}
46
47extension PlayerColor {
48    static let red = PlayerColor(id: "red", name: "Red", tint: .red, hue: 0)
49    static let orange = PlayerColor(id: "orange", name: "Orange", tint: .orange, hue: 30)
50    static let yellow = PlayerColor(id: "yellow", name: "Yellow", tint: .yellow, hue: 50)
51    static let green = PlayerColor(id: "green", name: "Green", tint: .green, hue: 130)
52    static let teal = PlayerColor(id: "teal", name: "Teal", tint: .teal, hue: 185)
53    static let blue = PlayerColor(id: "blue", name: "Blue", tint: .blue, hue: 215)
54    static let indigo = PlayerColor(id: "indigo", name: "Indigo", tint: .indigo, hue: 250)
55    static let purple = PlayerColor(id: "purple", name: "Purple", tint: .purple, hue: 285)
56    /// A rose pink at ~330°. SwiftUI's system pink sits near 350° and reads as
57    /// a second red, so a custom tint keeps it distinct from `red`.
58    static let pink = PlayerColor(
59        id: "pink",
60        name: "Pink",
61        tint: Color(red: 0.92, green: 0.32, blue: 0.62),
62        hue: 330
63    )
64
65    /// Order in which colours appear in any picker UI — sorted by hue.
66    static let palette: [PlayerColor] = [
67        .red, .orange, .yellow, .green, .teal, .blue, .indigo, .purple, .pink,
68    ]
69
70    /// Two colours whose hues are within this many degrees of each other are
71    /// treated as perceptually similar by `assignedColor`, so a participant is
72    /// kept clear of them — not only exact matches. Sized so a reserved blue
73    /// also rules out green (≈85° away), per the desired behaviour.
74    static let similarHueThreshold: Double = 90
75
76    /// Hand-curated companion palettes keyed by the *anchor* — the local
77    /// user's colour. Each anchor maps to a few ordered *options*; `gameID`
78    /// selects one, so a game's colours still vary game to game, while every
79    /// option is vetted to look good. The first `n` ids of an option cover an
80    /// `(n + 1)`-player game (anchor + `n` companions), so the ordering is
81    /// chosen to keep the 2- and 3-player prefixes well spaced too.
82    ///
83    /// Spacing was tuned on the *desaturated filled-cell wash* (tint at
84    /// `authorTintOpacity` over white) — where colours are hardest to tell
85    /// apart — using perceptual (OKLab ΔE) distance, not raw hue. That is why
86    /// pairs that look distinct at full saturation but collapse when washed
87    /// out (e.g. red/pink) never share an option. Built for up to four
88    /// players; larger games fall back to `assignedColor` for the surplus.
89    static let companionTable: [String: [[String]]] = [
90        "red": [["blue", "yellow", "green"], ["green", "indigo", "orange"], ["yellow", "teal", "indigo"]],
91        "orange": [["blue", "pink", "green"], ["green", "indigo", "red"], ["teal", "purple", "red"]],
92        "yellow": [["red", "blue", "green"], ["red", "teal", "indigo"], ["green", "indigo", "pink"]],
93        "green": [["red", "blue", "yellow"], ["blue", "pink", "orange"], ["red", "indigo", "orange"]],
94        "teal": [["red", "orange", "indigo"], ["red", "yellow", "purple"], ["yellow", "pink", "indigo"]],
95        "blue": [["red", "yellow", "green"], ["green", "pink", "orange"], ["red", "orange", "purple"]],
96        "indigo": [["red", "yellow", "green"], ["red", "orange", "teal"], ["orange", "green", "pink"]],
97        "purple": [["orange", "green", "red"], ["yellow", "teal", "red"], ["yellow", "green", "blue"]],
98        "pink": [["yellow", "blue", "green"], ["orange", "green", "indigo"], ["yellow", "teal", "indigo"]],
99    ]
100
101    /// Look up a colour by its stored identifier, falling back to blue.
102    static func color(for id: String) -> PlayerColor {
103        palette.first { $0.id == id } ?? .blue
104    }
105
106    /// Colours for the `authorIDs` collaborators in `gameID`, given the local
107    /// user's `anchor` colour. `authorIDs` is taken in the caller's stable
108    /// (sorted) order, and the returned array is aligned to it.
109    ///
110    /// Picks one curated option from `companionTable` for the anchor — seeded
111    /// by `gameID`, so the set varies between games — then rotates the handout
112    /// order by a second game-derived offset. That keeps each game's companion
113    /// set vetted while letting one-collaborator games use any colour in the
114    /// selected option instead of always taking the first slot. Any slots a
115    /// game needs beyond the option's length (or an anchor with no table
116    /// entry, which shouldn't happen for palette colours) fall back to the
117    /// legacy hue-spacing `assignedColor`, threaded so the surplus colours
118    /// stay distinct from the anchor and each other.
119    static func assignedCompanions(
120        forSortedAuthorIDs authorIDs: [String],
121        inGame gameID: UUID,
122        anchor: PlayerColor
123    ) -> [PlayerColor] {
124        let count = authorIDs.count
125        guard count > 0 else { return [] }
126
127        var colors: [PlayerColor] = []
128        if let options = companionTable[anchor.id], !options.isEmpty {
129            let gameSeed = gameID.uuidString
130            let option = options[stableIndex(for: "\(gameSeed)-option", count: options.count)]
131            let offset = stableIndex(for: "\(gameSeed)-offset", count: option.count)
132            let rotatedOption = option.indices.map { option[($0 + offset) % option.count] }
133            colors = rotatedOption.prefix(count).map { color(for: $0) }
134        }
135
136        if colors.count < count {
137            var taken = Set(colors.map(\.id))
138            taken.insert(anchor.id)
139            for authorID in authorIDs[colors.count..<count] {
140                let color = assignedColor(forAuthorID: authorID, inGame: gameID, reserved: taken)
141                taken.insert(color.id)
142                colors.append(color)
143            }
144        }
145        return colors
146    }
147
148    /// FNV-1a hash of `value` reduced into `0..<count`. A pure function, so
149    /// every process and device derives the same index for the same input.
150    /// Shared by avatar selection and stable colour assignment.
151    static func stableIndex(for value: String, count: Int) -> Int {
152        guard count > 0 else { return 0 }
153        let hash = value.utf8.reduce(UInt32(2_166_136_261)) { partial, byte in
154            (partial ^ UInt32(byte)) &* 16_777_619
155        }
156        return Int(hash % UInt32(count))
157    }
158
159    /// Circular distance between two hues, in degrees `0...180`.
160    static func hueDistance(_ a: Double, _ b: Double) -> Double {
161        let d = abs(a - b).truncatingRemainder(dividingBy: 360)
162        return min(d, 360 - d)
163    }
164
165    /// Highlight colour assigned to a collaborator *within one game*: filter the
166    /// palette down to the colours that are not just absent from `reserved` but
167    /// also more than `similarHueThreshold` degrees away from every reserved
168    /// colour's hue — so a collaborator never lands on a colour that looks like
169    /// one already taken (a reserved blue also rules out green, etc.) — then
170    /// hash `authorID` together with `gameID` to pick one of the survivors.
171    ///
172    /// Picking by hashing *into the eligible set* (rather than hashing to a base
173    /// index and linear-probing forward through the full palette) keeps the
174    /// choice uniform across the colours that are actually allowed. Probing
175    /// forward biases heavily toward whichever eligible colour sits just past
176    /// the largest contiguous block of rejected ones: e.g. against a reserved
177    /// blue the spacing rule rejects green…purple as a block, so a forward probe
178    /// landed on pink ~67% of the time. Hashing into the survivors spreads it
179    /// evenly instead.
180    ///
181    /// Folding `gameID` into the seed makes the colour deliberately *unstable*
182    /// across games: the same friend reads as a different colour in each game,
183    /// so a colour is felt as "whoever is in this grid" rather than a fixed
184    /// badge for a person. Callers thread the colours already handed out in the
185    /// game through `reserved`, so collaborators within a single game stay as
186    /// distinct as the palette allows. The local user is never assigned this
187    /// way — their colour is their stable preference, passed in via `reserved`.
188    ///
189    /// Degrades in two steps when the palette can't satisfy the spacing: first
190    /// relax to avoiding only the exact reserved colours, then, if every colour
191    /// is reserved, reuse the hashed base colour.
192    static func assignedColor(
193        forAuthorID authorID: String,
194        inGame gameID: UUID,
195        reserved: Set<String>
196    ) -> PlayerColor {
197        let seed = "\(gameID.uuidString)-\(authorID)"
198        let reservedHues = palette.filter { reserved.contains($0.id) }.map(\.hue)
199
200        // Pass 1: clear of every reserved hue (distance 0 covers exact matches).
201        let spaced = palette.filter { candidate in
202            reservedHues.allSatisfy { hueDistance($0, candidate.hue) > similarHueThreshold }
203        }
204        if let pick = pick(from: spaced, seed: seed) { return pick }
205
206        // Pass 2: palette too tight for hue spacing — avoid exact matches only.
207        let free = palette.filter { !reserved.contains($0.id) }
208        if let pick = pick(from: free, seed: seed) { return pick }
209
210        // Pass 3: everything reserved — reuse the hashed base colour.
211        return palette[stableIndex(for: seed, count: palette.count)]
212    }
213
214    /// Deterministically pick one colour from `candidates` by hashing `seed`
215    /// into the set. Returns `nil` when there is nothing to choose from.
216    private static func pick(from candidates: [PlayerColor], seed: String) -> PlayerColor? {
217        guard !candidates.isEmpty else { return nil }
218        return candidates[stableIndex(for: seed, count: candidates.count)]
219    }
220}