1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
//! # Veteran Data Extractor
//! The sub-modules contained in this module provide utilities and data structures for searching and extracting in-memory Veteran
//! character data from a running instance of _Uma Musume: Pretty Derby_ and exporting it to a JSON file widely accepted by tools across the web
//! for importing Veteran data.
//!
//! This crate implements the `log` crate and a logger can be implemented in your application that uses this facade to capture log messages.
//!
//! # Example
//! Here is a simple example of code that finds the running process, extracts the trained character data from memory, and exports it to a JSON
//! file.
//!
//! ```
//! use std::path::Path;
//!
//! use rusty_uma_extractor::vet_extractor::{
//! roster_extractor,
//! trained_character::{ deserialize_data, to_json_file }
//! };
//!
//! const TO_FILE_PATH: &str = "output/path/to/file/data.json";
//!
//! fn main() {
//!
//! let pid = roster_extractor::find_process().unwrap();
//! let scan_regions = roster_extractor::get_memmap(pid).unwrap();
//! let data: Option<roster_extractor::TrainedCharacterData> = match roster_extractor::chara_array_data_search(pid, scan_regions) {
//! Ok(Some(character_arr)) => match roster_extractor::get_chara_array(pid, character_arr) {
//! Ok(chara_array) => chara_array,
//! Err(e) => panic!("{}",e.to_string())
//! },
//! Ok(None) => {
//! println!("Could not find any mem regions containing character data!");
//! None
//! },
//! Err(e) => panic!("{}",e.to_string())
//! };
//!
//! if let Some(chara_data) = data {
//! let path = Path::new(TO_FILE_PATH);
//! match deserialize_data(chara_data) {
//! Ok(mut deser_data) => match to_json_file(&mut deser_data, path) {
//! Ok(_) => println!("Veteran roster data file written to: {:#?}",path.to_str()),
//! Err(e) => panic!("{}",e.to_string())
//! },
//! Err(e) => panic!("{}",e.to_string())
//! };
//! } else {
//! println!("Could not retrieve character data from mem region!")
//! }
//! }
//! ```
//! # NOTICE
//! It is **REQUIRED** that there already be a running instance of _Uma Musume: Pretty Derby_ present on the target device (aka your computer) and the _Veterans List_
//! page be opened before running this operation or **it will fail**.
//!
//! Due to the nature of how this operation is performed, by accessing regions in memory being actively used by the instance, it is not uncommon for this process to
//! still fail to find the trained character data array even if the above steps are followed. I have found the most consistency in success by doing the following:
//! - As soon as the instance is started, navigate to the _Veterans List_ page first thing and wait a few seconds (~5) to allow the instance to finish memory RW operations
//! before attempting to extract trained character data.
//! - If attempting to extract trained character data after instance has been running for sometime (perhaps after a campaign run) - there is a good chance the operation
//! may fail since this memory region hasn't been RW'd to in some time and therefore the region may no longer be present where it is usually expected. Some things to try
//! that I have had success with:
//! - Update something in the _Veterans List_ page (change an icon, transfer a character, ect,..), then re-open _Veterans List_.
//! - Back out and re-open _Veterans List_.
//! - Navigate to home screen and perform an action that causes an update (claim gifts, check on club, ect), then re-open _Veterans List_.
//! - Essentially anything that causes an update will allow an opportunity for that memory region containing the trained character data to surface again.
//! - If all else fails, simply restarting the instance and following the first point's steps usually remedies this and it succeeds.
//! - Still if no success, double check the binary/executable that is running the code has sufficient permissions to access the `/proc/{PID}/maps` and `/proc/{PID}/mem`
//! directories with read-only permissions which it requires to perform memory mapping functions.
/// Data structures for Veteran data along with utility functions for deserializing the data and exporting to JSON file.
/// Functions for finding and extracting the Veteran character data from a running instance of the game.