Scener SLM is an open-source Small Language Model (SLM) engineered for conditional procedural generation of FileRift-compatible *.scene level layout specifications for Swordigo. Developed under the OpenSwordigo organization, Scener SLM compresses complex spatial topology, component hierarchies, lighting rigs, entity placement, and trigger scripts into an ultra-lightweight causal decoder transformer architecture.
Scener SLM addresses the computational overhead of large subword language models by implementing a domain-tailored tokenization scheme. Instead of allocating tens of megabytes of memory to expansive general-purpose vocabularies, Scener SLM employs a compact, 320-token hybrid vocabulary. This vocabulary unifies domain-specific English prompt primitives, structural control boundary tokens, component class identifiers, and quantized spatial coordinate bins.
- Conditional Autoregressive Generation: Generates complete scene token streams bounded by control markers (
[OBJ_START],[COMP_START],[SCENE_END]). - Natural English Prompting: Translates natural language descriptions (e.g., level biome, difficulty, entity encounters, and hazard layouts) directly into executable FileRift scene structures without external LLM dependencies.
- Knowledge Distillation Pipelines: Integrates synthetic dataset streams derived from larger teacher models (Qwen and Gemini) incorporating Chain-of-Thought (CoT) spatial reasoning traces.
- Native FileRift Engine Compatibility: Outputs recode seamlessly via
ruby_cliinto binary.scenefiles for real-time rendering in the Ruby 3D Editor and target game runtime environments.
- Model Type: Causal Decoder-Only Transformer (GPT-Style)
- Framework: Raw PyTorch (Zero external transformer dependencies)
- Parameter Count: ~5.00 Million Parameters
- Layers (
n_layers): 6 - Attention Heads (
n_heads): 8 - Model Dimension (
d_model): 256 - Feedforward Dimension (
d_ff): 1024 - Context Window: 2048 Tokens
- Vocabulary Size: 320 Hybrid Tokens (11 Control, 121 English Prompt Primitives, 32 Scene Classes, 156 Position Bins)
- Memory Footprint: ~2.5 GB VRAM allocation during training (adam / FP16/BF16 mixed precision); < 100 MB VRAM during inference.
The model operates on a unified token index space defined in data/english_slm_datasets/english_vocab_dictionary.json:
Index Range Category Description
--------------------------------------------------------------------------------------------------
000 - 010 Special & Control Tokens [PAD], [BOS], [EOS], [PROMPT_START], [PROMPT_END],
[SCENE_START], [SCENE_END], [OBJ_START], [OBJ_END],
[COMP_START], [COMP_END]
011 - 131 English Prompt Words Domain vocabulary (e.g., forest, cave, boss, portal)
132 - 163 Scene Component Classes GroundMesh, Light, MonsterEntity, CollisionShape, etc.
164 - 319 Spatial Position Bins Quantized position markers (<POS_-5000> to <POS_9900>)
The project encompasses a comprehensive data collection for base training, prompt tuning, and teacher distillation:
Scener/
├── scener/ # Core PyTorch model & tokenizer packages
│ ├── model/ # Architecture implementation (GPT Transformer)
│ ├── data/ # Dataset loaders & token streaming pipelines
│ └── generation/ # Autoregressive generation utilities
├── tools/ # Scene parsing, normalization, & dataset analysis scripts
│ ├── parse_scene.py # FileRift text parser
│ ├── normalize_scene.py # Canonical JSON normalizer
│ └── analyze_dataset.py # Dataset distribution statistics calculator
├── scripts/ # High-level execution scripts
│ ├── prepare_dataset.py # Dataset builder & split compiler
│ ├── train.py # PyTorch training loop
│ └── generate.py # Inference script
└── data/ # Dataset repositories
├── decoded_scenes/ # Vanilla FileRift text scene specifications (202 files)
├── gemini_scenes/ # Remastered custom 3D mesh & object scene specifications
│ ├── master_custom_swordigo_forest_realms.scene
│ ├── custom_forest_part1_remastered.scene
│ ├── decoded/ # Custom decoded scene dumps
│ ├── encoded/ # Recoded binary scene dumps
│ └── dump/ # Legacy scene dumps
├── slm_datasets/ # Master JSON/JSONL dataset splits & manifests
├── english_slm_datasets/ # English hybrid dictionary & prompt training sets
├── qwen_distillation/ # Open-source Qwen teacher distillation datasets & guide
└── gemini_teacher/ # Gemini teacher spatial CoT reasoning datasets & guide
To enhance spatial coherence and layout diversity beyond the base game dataset, Scener SLM supports multi-teacher distillation:
- Synthetic Layout Generation: Teacher models generate candidate level topology adhering to FileRift schema requirements.
- Chain-of-Thought (CoT) Spatial Planning: Spatial reasoning steps (e.g., platform elevation bounds, hazard placement, lighting positions) are prepended to token streams during training to enforce structural constraints.
- Data Weighting Strategy: Training loops balance real decoded game scenes (weight = 1.0) with synthetic teacher sets (weight = 0.8) to maintain exact runtime compatibility while maximizing generative variety.
Ensure Python 3.8+ and PyTorch 2.0+ are installed. Clone the repository and add the project root to PYTHONPATH:
git clone https://github.com/OpenSwordigo/Scener.git
cd Scener
export PYTHONPATH=$(pwd)Tokenize decoded FileRift scene files and generate training splits:
python3 scripts/prepare_dataset.py \
--decoded-dir data/decoded_scenes \
--out-dir data/splits \
--val-ratio 0.10 \
--test-ratio 0.05Launch training using PyTorch:
python3 scripts/train.py --config configs/default_config.yamlGenerate a new .scene file from a checkpoint:
python3 scripts/generate.py \
--checkpoint checkpoints/best_model.pt \
--prompt "generate a forest scene with ground mesh torch light forest spirit monster and cave portal" \
--output output/generated_scene.sceneCompile the generated text .scene file to binary format using the native ruby_cli tool:
./bin/ruby_cli -r output/generated_scene.scene -o output/generated_scene_encoded.sceneThe resulting binary scene can be loaded directly into the Ruby 3D Editor or game client.
This project is open-source software licensed under the MIT License. Developed by the OpenSwordigo Organization.