Project Chimera
Меню

Исходники

466 строк · 27 КиБ

code/crates/chl-covers/src/lib.rs

1//! Автоматический поиск обложек для игр Chimera (не Steam/Epic/GOG — у тех
2//! обложка уже приходит из самого магазина, см. `chl_steam::art`,
3//! `chl_epic::covers`, `chl_gog::covers`).
4//!
5//! Несколько источников подряд, и ни один не требует от человека завести
6//! аккаунт, получить ключ API и вставить его в настройки — «поставил
7//! программу и она просто работает», а не «поставил и теперь донастрой
8//! сама»:
9//!
10//! 1. [`steam_search`] — открытая витрина Steam. Лучший источник по
11//! качеству и охвату среди игр, которые там хоть когда-то продавались.
12//! 2. [`gog_search`] — открытый каталог GOG.com. Каталог меньше, чем у
13//! Steam, но там, где игра есть, качество обложки не хуже.
14//! 3. [`wikipedia`] — картинка статьи в Википедии. Хуже по формату, но
15//! покрывает то, чего не было ни в Steam, ни в GOG (старые, редкие игры).
16//! 4. [`wikimedia_commons`] — прямой поиск по файлам Wikimedia Commons,
17//! шире статей Википедии: ловит обложки игр без отдельной статьи, но с
18//! загруженным туда бокс-артом. Самый широкий охват, но и самый шумный
19//! поиск — поэтому последний в очереди.
20//! 5. [`steamgriddb`] — общественная база обложек, качественнее всех
21//! выше, но требует свой ключ API. Не часть автоматической цепочки
22//! ([`fetch_cover_auto`] его не трогает вовсе) — это осознанно
23//! оставленная возможность для того, кто сам знает, что делает: если в
24//! переменной окружения `STEAMGRIDDB_API_KEY` лежит ключ, страница
25//! библиотеки использует и его тоже, молча и без единой настройки в
26//! интерфейсе. Нет переменной — модуль просто не вызывается.
27//!
28//! Каждый источник — свой сетевой запрос с коротким таймаутом: если один
29//! из них недоступен (заблокирован, перегружен, лежит), это не должно
30//! стопорить попытку со следующим на минуты — ровно та причина, по которой
31//! источников несколько, а не один.
32//!
33//! И у всех источников одно общее правило «это та самая игра» —
34//! [`title_match`]. Раньше его не было: каждый брал первый ответ поиска, а
35//! поиск магазина отвечает по нечёткому совпадению и почти всегда что-то
36//! предлагает. Так на плитке «GTA San Andreas - Definitive Edition»
37//! оказывалась машина ДПС с надписью «CRASH TIME» — первый ответ каталога
38//! GOG на этот запрос. Теперь непохожее отбрасывается, и `None` —
39//! нормальный результат: пустая плитка честнее уверенно чужой картинки, а
40//! выбрать обложку руками человек может всегда.
41
42pub mod gog_search;
43pub mod shape;
44pub mod steam_search;
45pub mod steamgriddb;
46pub mod title_match;
47pub mod wikimedia_commons;
48pub mod wikipedia;
49
50use std::path::{Path, PathBuf};
51
52/// Куда автопоиск кладёт обложку для игры `name`.
53///
54/// Правило одно на всех: библиотеку в интерфейсе докачивает `chl-gui`, а
55/// перепроверить и перекачать всё разом умеет `chl covers` — и оба должны
56/// попадать в один и тот же файл, иначе после команды в CLI лончер полез бы
57/// искать заново. Имя файла — FNV-1a от имени игры: в имени игры бывают и
58/// пробелы, и двоеточия, и кириллица, а хэш даёт короткое и безопасное имя
59/// на любой файловой системе.
60pub fn auto_cover_path(cache_dir: &Path, name: &str) -> PathBuf {
61 cache_dir.join(format!("{:016x}.jpg", name_hash(name)))
62}
63
64/// То же самое, но для широкого баннера (`Game::hero`) — свой файл, не
65/// обложка: разные по форме картинки одной игры не могут делить один путь,
66/// иначе вторая закачка молча перепишет первую. Суффикс `-hero` в имени
67/// файла, а не отдельный каталог — рядом проще смотреть глазами, что уже
68/// накачано.
69pub fn auto_hero_path(cache_dir: &Path, name: &str) -> PathBuf {
70 cache_dir.join(format!("{:016x}-hero.jpg", name_hash(name)))
71}
72
73fn name_hash(name: &str) -> u64 {
74 let mut hash = 0xcbf29ce484222325u64;
75 for b in name.bytes() {
76 hash ^= b as u64;
77 hash = hash.wrapping_mul(0x100000001b3);
78 }
79 hash
80}
81
82/// Отметка «по этой игре уже искали и не нашли».
83///
84/// Появилась вместе с правилом выбора ([`title_match`]): раньше поиск почти
85/// всегда что-нибудь возвращал, и «без обложки» было редким временным
86/// состоянием. Теперь это нормальный и постоянный исход — у приватного
87/// сервера WoW или у апплета Wine обложки нет и не будет. А докач в
88/// интерфейсе перебирает игры без обложки при каждом открытии «Библиотеки»,
89/// и без отметки те же четыре сетевых запроса на каждую такую игру уходили
90/// бы снова и снова, вечно, ради того же самого «не нашлось».
91fn miss_marker(cache_dir: &Path, name: &str) -> PathBuf {
92 cache_dir.join(format!("{:016x}.не-нашлось", name_hash(name)))
93}
94
95/// Сколько «не нашлось» считается свежим. Месяц — не вечность нарочно:
96/// игру могли добавить в магазин, статью в Википедию, а обложку на
97/// Commons; раз в месяц спросить заново дёшево.
98const MISS_TTL: std::time::Duration = std::time::Duration::from_secs(30 * 24 * 3600);
99
100/// Искали ли по этой игре недавно и не нашли. Дальше спрашивать сеть
101/// незачем — ответ уже известен.
102///
103/// `elapsed()` возвращает ошибку, если метка файла лежит в будущем, и
104/// `.ok()` превращает это в «не свежо», то есть спросить заново. Так и
105/// надо, и это не случайность, а требование: отказ должен склоняться в
106/// сторону лишней работы, а не в сторону молчания. Соблазн упростить до
107/// `unwrap_or(Duration::ZERO)` даёт возраст ноль, то есть метку из
108/// будущего свежей НАВСЕГДА — обложка не появилась бы уже никогда, и
109/// заметить это было бы нечем: в интерфейсе просто нет картинки.
110///
111/// Метка из будущего — не выдумка: время на машине переводят, файлы
112/// приезжают с внешнего диска и из архивов, а на соседней машине этого
113/// проекта часы даёт гипервизор, а не NTP. Поведение закреплено тестом
114/// `метка_из_будущего_считается_несвежей`.
115pub fn recently_missed(cache_dir: &Path, name: &str) -> bool {
116 let Ok(meta) = std::fs::metadata(miss_marker(cache_dir, name)) else {
117 return false;
118 };
119 meta.modified().ok().and_then(|t| t.elapsed().ok()).is_some_and(|age| age < MISS_TTL)
120}
121
122/// Запомнить, что не нашлось, или — при `found` — забыть прошлое «не
123/// нашлось»: обложка появилась, отметка больше не про эту игру.
124pub fn remember_miss(cache_dir: &Path, name: &str, found: bool) {
125 let marker = miss_marker(cache_dir, name);
126 if found {
127 std::fs::remove_file(&marker).ok();
128 return;
129 }
130 std::fs::create_dir_all(cache_dir).ok();
131 std::fs::write(&marker, b"").ok();
132}
133
134/// Пробует источники по очереди, первый успех побеждает. Тихо возвращает
135/// `None`, если ни один ничего не нашёл, — это не ошибка конкретной игры, а
136/// честное «не нашлось нигде», ручной выбор обложки остаётся доступен
137/// всегда.
138///
139/// `steamgriddb` сюда не входит: у него другое условие вызова (переменная
140/// окружения с ключом), см. doc-комментарий модуля — решает вызывающий код
141/// (`chl-gui::library`), а не эта функция.
142pub fn fetch_cover_auto(title: &str, dest: &Path) -> Option<PathBuf> {
143 if let Some(path) = try_all_sources(title, dest) {
144 return Some(path);
145 }
146 // Второй заход — тем же названием без хвоста про издание. Поиск
147 // магазина ищет по строке целиком, и «Grand Theft Auto Vice City
148 // Nextgen Edition» не находит ничего, хотя «Grand Theft Auto Vice
149 // City» находит сразу (проверено 2026-09-07). Правило выбора при этом
150 // не смягчается: служебные слова `title_match` всё равно не считает
151 // значащими, так что найденное проверяется ровно так же.
152 let core = title_match::search_query_core(title)?;
153 try_all_sources(&core, dest)
154}
155
156/// Ищет широкий баннер по названию игры.
157///
158/// До этого баннер умел находиться только через SteamGridDB, а он требует
159/// ключа в переменной окружения — то есть у подавляющего большинства не
160/// находился вовсе, и шапка страницы игры оставалась сплошным цветом у
161/// всех, кроме игр Steam (у тех баннер приходит вместе с импортом).
162///
163/// Источник один — витрина Steam: она отдаёт широкий фон страницы игры и
164/// не требует ни ключа, ни регистрации. Игра при этом не обязана быть
165/// куплена в Steam, достаточно чтобы она там продавалась: для «World of
166/// Warcraft» или репака GTA этого хватает. Не нашлось — значит не
167/// нашлось, и ручной выбор картинки остаётся.
168pub fn fetch_hero_auto(title: &str, dest: &Path) -> Option<PathBuf> {
169 if let Some(path) = keep_if(steam_search::fetch_hero(title, dest), shape::Shape::Wide) {
170 return Some(path);
171 }
172 // Тот же второй заход, что у обложки: название без хвоста про издание.
173 let core = title_match::search_query_core(title)?;
174 keep_if(steam_search::fetch_hero(&core, dest), shape::Shape::Wide)
175}
176
177/// Поиск обложки по названию в одном источнике.
178type Source = fn(&str, &Path) -> anyhow::Result<Option<PathBuf>>;
179
180/// Первый источник, отдавший постер. Картинка другой формы — не находка:
181/// файл стирается, и очередь идёт дальше (OpenProject #392). Википедия и
182/// Commons отдают то, что стоит в статье, — бывает и скриншот, и логотип.
183fn try_all_sources(title: &str, dest: &Path) -> Option<PathBuf> {
184 let sources: [Source; 4] = [
185 steam_search::fetch_cover,
186 gog_search::fetch_cover,
187 wikipedia::fetch_cover,
188 wikimedia_commons::fetch_cover,
189 ];
190 sources.into_iter().find_map(|fetch| keep_if(fetch(title, dest), shape::Shape::Poster))
191}
192
193/// Найденное — если оно нужной формы; иначе файл убирается.
194pub fn keep_if(found: anyhow::Result<Option<PathBuf>>, want: shape::Shape) -> Option<PathBuf> {
195 let path = found.ok().flatten()?;
196 if shape::shape(&path) == Some(want) {
197 return Some(path);
198 }
199 std::fs::remove_file(&path).ok();
200 None
201}
202
203/// Вариант обложки для окна «Подобрать обложку заново».
204#[derive(Debug, Clone)]
205pub struct Candidate {
206 /// Откуда: «Steam», «GOG.com», «SteamGridDB», «Википедия», «Commons».
207 pub source: &'static str,
208 /// Какую игру источник нашёл — чтобы человек видел совпадение, а не
209 /// только картинку.
210 pub title: String,
211 pub path: PathBuf,
212}
213
214/// Сколько вариантов показывать: больше шести на экран не помещается и
215/// выбирать из них уже трудно.
216pub const MAX_CANDIDATES: usize = 6;
217
218/// Несколько постеров из разных источников — все сразу, параллельно, в
219/// `dir` (прежние файлы там стираются). Только постеры: баннер среди
220/// вариантов обложки — тот же растянутый баннер в карточке.
221///
222/// Порядок — по надёжности совпадения: Steam по appid (точно та игра),
223/// витрина Steam по названию (до трёх изданий), SteamGridDB (если есть
224/// ключ), GOG, Википедия, Commons. Одинаковые картинки с разных зеркал и
225/// источников склеиваются по размеру файла.
226pub fn poster_candidates(
227 query: &str,
228 steam_appid: Option<u64>,
229 steamgriddb_key: Option<&str>,
230 dir: &Path,
231) -> Vec<Candidate> {
232 std::fs::remove_dir_all(dir).ok();
233 if std::fs::create_dir_all(dir).is_err() {
234 return Vec::new();
235 }
236 // Каждая загрузка — своим потоком, а не по очереди внутри источника:
237 // зависшее зеркало Steam держит каждую до таймаута, и четыре обложки
238 // Steam подряд — это полминуты ожидания в открытом окне.
239 let steam_matches = std::thread::scope(|scope| {
240 let matches = scope.spawn(|| steam_search::search_matches(query).unwrap_or_default());
241 let gog = scope.spawn(|| gog_search::search_covers(query).unwrap_or_default());
242 (matches.join().unwrap_or_default(), gog.join().unwrap_or_default())
243 });
244 let (matches, gog) = steam_matches;
245 let mut steam: Vec<(u64, String)> = steam_appid.map(|a| (a, format!("appid {a}"))).into_iter().collect();
246 steam.extend(matches.into_iter().filter(|(a, _)| Some(*a) != steam_appid).take(3));
247
248 let groups: Vec<Vec<Candidate>> = std::thread::scope(|scope| {
249 let mut jobs = Vec::new();
250 for (i, (appid, title)) in steam.into_iter().enumerate() {
251 jobs.push(scope.spawn(move || {
252 let dest = dir.join(format!("steam-{i}.jpg"));
253 match steam_search::fetch_cover_by_appid(appid, &dest) {
254 Ok(Some(path)) => vec![Candidate { source: "Steam", title, path }],
255 _ => Vec::new(),
256 }
257 }));
258 }
259 jobs.push(scope.spawn(|| {
260 let Some(key) = steamgriddb_key else { return Vec::new() };
261 steamgriddb::fetch_covers(key, query, dir, 3)
262 .unwrap_or_default()
263 .into_iter()
264 .map(|(path, title)| Candidate { source: "SteamGridDB", title, path })
265 .collect()
266 }));
267 for (i, (title, url)) in gog.into_iter().take(2).enumerate() {
268 jobs.push(scope.spawn(move || {
269 let dest = dir.join(format!("gog-{i}.jpg"));
270 match gog_search::download(&url, &dest) {
271 Ok(()) => vec![Candidate { source: "GOG.com", title, path: dest }],
272 Err(_) => Vec::new(),
273 }
274 }));
275 }
276 jobs.push(scope.spawn(|| {
277 let dest = dir.join("wikipedia.jpg");
278 match wikipedia::fetch_cover(query, &dest) {
279 Ok(Some(path)) => vec![Candidate { source: "Википедия", title: query.to_string(), path }],
280 _ => Vec::new(),
281 }
282 }));
283 jobs.push(scope.spawn(|| {
284 let dest = dir.join("commons.jpg");
285 match wikimedia_commons::fetch_cover(query, &dest) {
286 Ok(Some(path)) => vec![Candidate { source: "Commons", title: query.to_string(), path }],
287 _ => Vec::new(),
288 }
289 }));
290 jobs.into_iter().map(|h| h.join().unwrap_or_default()).collect()
291 });
292
293 let mut seen: Vec<u64> = Vec::new();
294 let mut out = Vec::new();
295 for c in groups.into_iter().flatten() {
296 let size = std::fs::metadata(&c.path).map(|m| m.len()).unwrap_or(0);
297 if !shape::is_poster(&c.path) || seen.contains(&size) {
298 std::fs::remove_file(&c.path).ok();
299 continue;
300 }
301 seen.push(size);
302 out.push(c);
303 }
304 for extra in out.split_off(out.len().min(MAX_CANDIDATES)) {
305 std::fs::remove_file(&extra.path).ok();
306 }
307 out
308}
309
310/// Куда кладётся обложка, выбранная человеком: из вариантов или своя.
311///
312/// В данных, а не в кэше: это выбор человека, и очистка кэша не должна его
313/// уносить. И отдельно от `covers-auto`: `chl covers fix` и докач
314/// переписывают только найденное автоматически, а выбранное руками не
315/// трогают — по каталогу их и различают.
316pub fn picked_cover_path(data_dir: &Path, name: &str, ext: &str) -> PathBuf {
317 data_dir.join("covers").join(format!("{:016x}.{ext}", name_hash(name)))
318}
319
320/// Подменная обложка купленной, но не установленной игры — когда магазин
321/// отдал картинку не той формы (GOG — широкий фон страницы, Epic у
322/// дополнений — квадрат). `key` — ключ записи магазина в сетке.
323pub fn store_cover_path(cache_dir: &Path, key: &str) -> PathBuf {
324 auto_cover_path(cache_dir, key)
325}
326
327#[cfg(test)]
328mod tests_свежесть {
329 use super::*;
330
331 /// Метка «не нашлось» со временем в будущем не должна считаться
332 /// свежей. Иначе она заблокировала бы поиск обложки навсегда:
333 /// возраст никогда не превысит срок, а в интерфейсе это выглядит
334 /// просто как отсутствующая картинка — жаловаться будет нечему.
335 ///
336 /// Тест держит именно эту границу, а не срок: `unwrap_or` вместо
337 /// `.ok()` в `recently_missed` его роняет.
338 #[test]
339 fn метка_из_будущего_считается_несвежей() {
340 let d = std::env::temp_dir().join("chl-test-covers-свежесть");
341 std::fs::remove_dir_all(&d).ok();
342 std::fs::create_dir_all(&d).unwrap();
343
344 // Свежая метка: поиск не нужен.
345 std::fs::write(miss_marker(&d, "игра"), "").unwrap();
346 assert!(recently_missed(&d, "игра"), "только что записанная метка свежая");
347
348 // Та же метка, но со временем на сутки вперёд.
349 let сутки_вперёд = std::time::SystemTime::now() + std::time::Duration::from_secs(86_400);
350 let f = std::fs::File::options()
351 .write(true)
352 .open(miss_marker(&d, "игра"))
353 .unwrap();
354 f.set_times(std::fs::FileTimes::new().set_modified(сутки_вперёд)).unwrap();
355 drop(f);
356
357 assert!(
358 !recently_missed(&d, "игра"),
359 "метка из будущего должна склонять к лишнему поиску, а не к вечному молчанию"
360 );
361
362 std::fs::remove_dir_all(&d).ok();
363 }
364}
365
366/// Ищет постер для игры из библиотеки — общий путь для докача в
367/// интерфейсе, кнопки на странице игры и `chl covers fix`.
368///
369/// Очередь: картинка из папки игры (если это постер), у игры Steam —
370/// обложка по appid (точно та игра, без угадывания по названию), затем
371/// автопоиск по очищенному названию ([`title_match::clean_title`]:
372/// «World of Warcraft 3.3.5a InsaneRamZes» ищется как «World of
373/// Warcraft»), затем SteamGridDB, если есть ключ. Всё найденное — только
374/// постеры; не нашлось — `None`, и плитка рисуется заглушкой.
375pub fn find_for_game(
376 name: &str,
377 exe: &Path,
378 steam_appid: Option<u32>,
379 dest: &Path,
380 steamgriddb_key: Option<&str>,
381) -> Option<PathBuf> {
382 let local = exe.parent().filter(|_| exe.is_absolute()).and_then(chl_core::local_art::find);
383 if let Some(path) = local.filter(|p| shape::is_poster(p)) {
384 return Some(path);
385 }
386 if let Some(appid) = steam_appid
387 && let Ok(Some(path)) = steam_search::fetch_cover_by_appid(appid.into(), dest)
388 {
389 return Some(path);
390 }
391 let query = title_match::clean_title(name);
392 fetch_cover_auto(&query, dest).or_else(|| {
393 let key = steamgriddb_key?;
394 keep_if(steamgriddb::fetch_cover(key, &query, dest), shape::Shape::Poster)
395 })
396}
397
398/// Откуда у игры обложка — от этого зависит, можно ли её заменить
399/// найденной автоматически.
400#[derive(Debug, Clone, Copy, PartialEq, Eq)]
401pub enum Origin {
402 /// Из кэша Steam.
403 Steam,
404 /// Нашёл автопоиск (`covers-auto`).
405 Auto,
406 /// Картинка из папки игры.
407 GameFolder,
408 /// Выбрана человеком из вариантов или своя ([`picked_cover_path`]).
409 Picked,
410 /// Любой другой файл — его указали руками.
411 Own,
412}
413
414impl Origin {
415 /// Заменять ли её найденной автоматически, если она не той формы.
416 /// Выбранное человеком — нет: его выбор важнее пропорции.
417 pub fn replaceable(self) -> bool {
418 !matches!(self, Origin::Picked | Origin::Own)
419 }
420
421 pub fn title(self) -> &'static str {
422 match self {
423 Origin::Steam => "кэш Steam",
424 Origin::Auto => "автопоиск",
425 Origin::GameFolder => "папка игры",
426 Origin::Picked => "выбрана",
427 Origin::Own => "своя",
428 }
429 }
430}
431
432/// Откуда картинка `cover` у игры с исполняемым файлом `exe`.
433pub fn origin(cover: &Path, exe: &Path, auto_cache: &Path, data_dir: &Path) -> Origin {
434 if cover.starts_with(auto_cache) {
435 Origin::Auto
436 } else if cover.starts_with(data_dir.join("covers")) {
437 Origin::Picked
438 } else if cover.components().any(|c| c.as_os_str() == "librarycache") {
439 Origin::Steam
440 } else if exe.is_absolute() && exe.parent().is_some_and(|d| cover.parent() == Some(d)) {
441 Origin::GameFolder
442 } else {
443 Origin::Own
444 }
445}
446
447#[cfg(test)]
448mod tests_происхождение {
449 use super::*;
450
451 #[test]
452 fn выбранное_человеком_не_заменяется() {
453 let auto = Path::new("/c/covers-auto");
454 let data = Path::new("/d/chimera-launcher");
455 let exe = Path::new("/games/x/x.exe");
456 let o = |p: &str| origin(Path::new(p), exe, auto, data);
457 assert_eq!(o("/c/covers-auto/1.jpg"), Origin::Auto);
458 assert_eq!(o("/d/chimera-launcher/covers/1.jpg"), Origin::Picked);
459 assert_eq!(o("/h/.steam/steam/appcache/librarycache/10/library_600x900.jpg"), Origin::Steam);
460 assert_eq!(o("/games/x/cover.jpg"), Origin::GameFolder);
461 assert_eq!(o("/home/me/Картинки/x.png"), Origin::Own);
462 assert!(Origin::Auto.replaceable() && Origin::Steam.replaceable() && Origin::GameFolder.replaceable());
463 assert!(!Origin::Picked.replaceable() && !Origin::Own.replaceable());
464 }
465}
466