T-Detector (macOS + Offline Cluster Radar)

This is a refined version of the original 《T-detector: A Trajectory based Pretrained Model for Game Bot Detection in MMORPGs》, adapted for modern macOS (ARM64) development environments and extended with an offline cluster radar workflow for latent-space behavioral analysis.

Base Repository: aker218/T-Detector

macOS Compatibility Refinements

The original codebase (designed for Python 3.6/3.7) has been upgraded and patched to support macOS ARM64 (M1/M2/M3) and Python 3.12+:

1. Gensim 4.0+ Integration:
   • Updated Word2Vec parameters: size → vector_size.
   • Updated iter → epochs.
   • Fixed vocabulary access for modern Gensim API.
2. Transformer & PyTorch Upgrades:
   • Migrated AdamW and BertLayerNorm imports to standard torch.optim and torch.nn for compatibility with transformers 4.x.
3. Dependency Cleanup:
   • Removed DGL library dependencies to bypass C++ compilation errors on ARM64 macOS.
   • Replaced deprecated NumPy aliases (e.g., np.int, np.float) with standard Python types to prevent runtime crashes.
4. Stability Fixes:
   • Resolved directory creation typos (makedirs(exists_ok=True)).
   • Patched trainer.py to handle zero-loss batches during initial pre-training phases.
   • Fixed sequence length calculation logic in models.py.

New Features: Offline Cluster Radar

The repo now includes an offline analysis layer on top of the original supervised T-Detector pipeline:

• Feature Extraction: Extract session-level latent vectors from the trained encoders.
• High-Dimensional Clustering: Cluster embeddings in normalized high-dimensional space with HDBSCAN.
• 2D Radar Visualization: Project latent vectors to 2D with UMAP and render them with Plotly WebGL.
• Map-Level Analysis: Analyze one map at a time to avoid cross-map behavior mixing.
• Interactive Review:
  • Search by AccID/UserID
  • Highlight clusters and outliers
  • Open session trajectory plots
  • Generate latent profile summaries

This layer is meant for offline investigation and presentation. It does not replace the original supervised classifier.

Environment Setup

Recommended Environment: Python 3.12+

# Core Dependencies
pip install numpy pandas scipy scikit-learn tqdm torch transformers gensim

# Visualization Dependencies
pip install umap-learn hdbscan plotly matplotlib

Directory Structure

T-Detector
├── train_data/                             # Full raw session data (move / mouse)
├── train_data_sampled/                     # Sampled session data
├── train_data_sampled_processed/           # Processed sampled features / vocab / merge-split
├── trajectory_detector/
│   ├── angle_pretrain.py                   # Angle pretraining
│   ├── train_and_evaluate.py               # Supervised training / evaluation
│   ├── extract_features.py                 # Extract latent features for clustering
│   ├── visualize_2d.py                     # Generic radar visualization
│   ├── explain_behavior.py                 # Latent profile summary
│   ├── dataset.py                          # Torch dataset logic
│   ├── models.py                           # T-Detector model architecture
│   ├── trainer.py                          # Training utilities
│   └── run.sh                              # Original pipeline entry
├── map_analyzer.py                         # Map-level offline clustering + radar HTML
├── player_trajectory_viewer.py             # Render move / mouse session plots
├── bridge_server.py                        # Local HTTP bridge for HTML tool buttons
└── analysis_results/                       # Generated reports / radar pages / logs

Quick Start

1. Extract Features from a Pretrained Checkpoint

If you need sampled latent features:

python3 trajectory_detector/extract_features.py \
  -D ./train_data_sampled_processed \
  -C ./trajectory_detector/models/train_data_sampled_processed_script_data_model/merge_split_embedding_ConvGRU_mutual_attention_residual(rnn_input)_fusion_without_fre_100_trainset(ptretrain)/checkpoint-1248/model.pt \
  -O extracted_sampled \
  --feature_mode encoder_concat

2. Launch a Generic Radar View on Sampled Features

python3 trajectory_detector/visualize_2d.py \
  --features ./train_data_sampled_processed/extracted_sampled_features.npy \
  --meta ./train_data_sampled_processed/extracted_sampled_meta.json \
  --output ./train_data_sampled_radar_vision.html \
  --min_cluster_size 30 \
  --min_samples 10 \
  --pca_dim 32

3. Run Map-Level Offline Analysis

For a real map-level radar page, prefer map_analyzer.py.

If map-specific full features already exist:

python3 map_analyzer.py \
  --mapid 338 \
  --train_data ./train_data \
  --output ./analysis_results \
  --min_cluster_size 30 \
  --min_samples 10 \
  --pca_dim 32

If full map features do not exist yet, build them directly from raw sessions and then cluster:

python3 map_analyzer.py \
  --mapid 338 \
  --train_data ./train_data \
  --output ./analysis_results \
  --build_from_raw \
  --processed_dir ./train_data_sampled_processed \
  --min_cluster_size 30 \
  --min_samples 10 \
  --pca_dim 32 \
  --feature_batch_size 32

This generates:

• analysis_results/map_338/train_data_338_radar_vision.html
• analysis_results/map_338/train_data_338_cluster_report.md
• analysis_results/map_338/filtered_features.npy
• analysis_results/map_338/filtered_meta.json

4. Optional: Enable HTML Tool Buttons

To make PLOT TRAJECTORY and EXPLAIN LATENT PROFILE buttons work from the generated HTML:

python3 bridge_server.py

Keep that process running while you open the radar HTML.

Notes

• visualize_2d.py is the generic feature viewer.
• map_analyzer.py is the recommended entry point for offline map investigation.
• Clustering is performed in high-dimensional embedding space; UMAP is used only for visualization.
• The current offline radar is an analysis tool built on top of the supervised T-Detector model. It is not yet a fully unsupervised binary classifier.

---

Maintained by williammuji. Original research by the T-Detector authors.