john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

[Minor Feature] Packaging variants: light vs batteries-included #163

New issue
Closed
opened 2025-12-29 03:54:02 +00:00 by john · 2 comments
john commented 2025-12-29 03:54:02 +00:00
Owner
Copy link

Summary

Current builds have dramatically different sizes:

  • Windows zip: ~14 MB (no Python stdlib)
  • Linux bz2: ~82 MB (full Python stdlib)

Games that are "pure McRogueFace" may only need import mcrfpy and optionally sys.exit() - no stdlib at all.

Proposed Variants

Light Build (~15-20 MB)

  • McRogueFace executable
  • Core assets (if any)
  • Minimal Python: just mcrfpy module, sys, builtins
  • Target: simple games, demos, tutorials

Full Build (~80+ MB)

  • Everything in Light
  • Complete Python 3.12 standard library
  • Target: complex games using json, pathlib, random, collections, etc.

Implementation

  1. Identify minimal Python modules required for mcrfpy to function
  2. Create build script that can produce either variant
  3. Document which stdlib modules are available in each
  4. Test both variants with existing demos

Questions

  • Should Light include random? (Very commonly needed for games)
  • Should Light include json? (Useful for save files)
  • What's the actual minimal set that covers 80% of use cases?

Related

  • Cross-compilation issue (build both variants for both platforms)
  • Could create "stdlib bundles" users can add to Light builds
## Summary Current builds have dramatically different sizes: - **Windows zip**: ~14 MB (no Python stdlib) - **Linux bz2**: ~82 MB (full Python stdlib) Games that are "pure McRogueFace" may only need `import mcrfpy` and optionally `sys.exit()` - no stdlib at all. ## Proposed Variants ### Light Build (~15-20 MB) - McRogueFace executable - Core assets (if any) - Minimal Python: just `mcrfpy` module, `sys`, `builtins` - Target: simple games, demos, tutorials ### Full Build (~80+ MB) - Everything in Light - Complete Python 3.12 standard library - Target: complex games using `json`, `pathlib`, `random`, `collections`, etc. ## Implementation 1. Identify minimal Python modules required for `mcrfpy` to function 2. Create build script that can produce either variant 3. Document which stdlib modules are available in each 4. Test both variants with existing demos ## Questions - Should Light include `random`? (Very commonly needed for games) - Should Light include `json`? (Useful for save files) - What's the actual minimal set that covers 80% of use cases? ## Related - Cross-compilation issue (build both variants for both platforms) - Could create "stdlib bundles" users can add to Light builds
john commented 2026-01-07 05:07:59 +00:00
Author
Owner
Copy link

Preliminary Research Findings

Current Build Size Breakdown

Component Size Notes
libpython3.14.so 33.6 MB Python interpreter (required)
Lib/ (pure Python stdlib) 56 MB Full standard library
lib.linux-x86_64-3.14/ (C extensions) 26 MB 83 compiled modules
Total Python ~116 MB

Definitely Removable (Development/Testing Only)

These are never needed for game distribution:

Component Size Purpose
Lib/test/ 34 MB Python's test suite
Lib/idlelib/ 1.9 MB IDLE IDE
Lib/ensurepip/ 1.7 MB pip installer bundling
Lib/tkinter/ 320 KB Tkinter GUI (not used)
Lib/turtledemo/ 116 KB Turtle graphics demos
Test C extensions (*test*.so) 4.1 MB 11 test modules
Subtotal ~42 MB Immediately removable

Just removing these brings Linux from ~82 MB → ~40 MB.

Engine Requirements from Stdlib

The C++ engine imports enum for Easing, Transition, and FOV enum types:

  • src/PyEasing.cpp - PyImport_ImportModule("enum")
  • src/PyTransition.cpp - PyImport_ImportModule("enum")
  • src/PyFOV.cpp - PyImport_ImportModule("enum")

The enum module has minimal dependencies (only builtins).

Game Script Module Usage Analysis

Analyzed all scripts in src/scripts/, tests/, and tests/demo/:

Highly Used (essential for most games):

  • random - 8+ files (enemy AI, loot tables, level generation)
  • sys - 20+ files (exit codes, test infrastructure)
  • math - 5+ files (geometry, pathfinding, visibility)

Moderately Used (useful for complex games):

  • dataclasses - 5 files (item system, data structures)
  • pathlib - 3 files (path handling)
  • json - 2+ files (save files, benchmarking)
  • os - 5+ files (environment, cross-platform)

Light Usage (optional/demo-only):

  • code - 1 file (interactive console for debugging)
  • typing, enum, re, datetime, base64 - AI/vLLM demos only

Dependency Chains

random module imports:

math, os, _random (C), bisect, operator, itertools, _collections_abc

json module imports:

codecs, json.decoder, json.encoder

Proposed Build Variants

1. Ultra-Light Build (~20 MB target)

Removes everything except:

  • libpython3.14.so (required)
  • enum (required by engine)
  • encodings/ subset (utf_8, ascii, latin_1)
  • importlib/ (required for imports)
  • Core builtins (sys, builtins - built into libpython)

Use case: Demos, tutorials, games that only use mcrfpy API

2. Game-Ready Build (~25-30 MB target)

Adds to Ultra-Light:

  • random + dependencies (math, bisect, operator, itertools)
  • json + codecs

Use case: Most typical roguelike games

3. Full Build (~40 MB)

Current build minus development cruft:

  • Remove test/, idlelib/, ensurepip/, tkinter/, turtledemo/
  • Remove test C extensions
  • Keep everything else

Use case: Complex games, games using networking, async, etc.

Questions for Implementation

  1. Encodings: The encodings/ directory has 124 files (1.8 MB). Games likely only need UTF-8. Should we strip to essentials?

  2. __pycache__: Currently 3.9 MB in Lib/. Pre-compiled .pyc files speed startup but could be regenerated on first run.

  3. Build script approach:

    • Option A: Multiple CMake build profiles
    • Option B: Post-build stripping script
    • Option C: Separate __lib_light/ and __lib_full/ directories

  4. Random included by default? The issue asks this - based on usage analysis, yes - it's used in 8+ game files and is essential for roguelike mechanics.

Next Steps

  1. Create a stripping script that removes the definite cruft (~42 MB savings)
  2. Test that McRogueFace still runs after stripping
  3. Identify the true minimal set for Ultra-Light
  4. Update CMakeLists.txt to support build profiles
## Preliminary Research Findings ### Current Build Size Breakdown | Component | Size | Notes | |-----------|------|-------| | `libpython3.14.so` | 33.6 MB | Python interpreter (required) | | `Lib/` (pure Python stdlib) | 56 MB | Full standard library | | `lib.linux-x86_64-3.14/` (C extensions) | 26 MB | 83 compiled modules | | **Total Python** | **~116 MB** | | ### Definitely Removable (Development/Testing Only) These are **never needed** for game distribution: | Component | Size | Purpose | |-----------|------|---------| | `Lib/test/` | **34 MB** | Python's test suite | | `Lib/idlelib/` | 1.9 MB | IDLE IDE | | `Lib/ensurepip/` | 1.7 MB | pip installer bundling | | `Lib/tkinter/` | 320 KB | Tkinter GUI (not used) | | `Lib/turtledemo/` | 116 KB | Turtle graphics demos | | Test C extensions (`*test*.so`) | 4.1 MB | 11 test modules | | **Subtotal** | **~42 MB** | Immediately removable | Just removing these brings Linux from ~82 MB → ~40 MB. ### Engine Requirements from Stdlib The C++ engine **imports `enum`** for Easing, Transition, and FOV enum types: - `src/PyEasing.cpp` - `PyImport_ImportModule("enum")` - `src/PyTransition.cpp` - `PyImport_ImportModule("enum")` - `src/PyFOV.cpp` - `PyImport_ImportModule("enum")` The `enum` module has minimal dependencies (only builtins). ### Game Script Module Usage Analysis Analyzed all scripts in `src/scripts/`, `tests/`, and `tests/demo/`: **Highly Used** (essential for most games): - `random` - 8+ files (enemy AI, loot tables, level generation) - `sys` - 20+ files (exit codes, test infrastructure) - `math` - 5+ files (geometry, pathfinding, visibility) **Moderately Used** (useful for complex games): - `dataclasses` - 5 files (item system, data structures) - `pathlib` - 3 files (path handling) - `json` - 2+ files (save files, benchmarking) - `os` - 5+ files (environment, cross-platform) **Light Usage** (optional/demo-only): - `code` - 1 file (interactive console for debugging) - `typing`, `enum`, `re`, `datetime`, `base64` - AI/vLLM demos only ### Dependency Chains **`random` module imports:** ``` math, os, _random (C), bisect, operator, itertools, _collections_abc ``` **`json` module imports:** ``` codecs, json.decoder, json.encoder ``` ### Proposed Build Variants #### 1. Ultra-Light Build (~20 MB target) **Removes everything except:** - `libpython3.14.so` (required) - `enum` (required by engine) - `encodings/` subset (utf_8, ascii, latin_1) - `importlib/` (required for imports) - Core builtins (sys, builtins - built into libpython) **Use case:** Demos, tutorials, games that only use `mcrfpy` API #### 2. Game-Ready Build (~25-30 MB target) **Adds to Ultra-Light:** - `random` + dependencies (math, bisect, operator, itertools) - `json` + codecs **Use case:** Most typical roguelike games #### 3. Full Build (~40 MB) **Current build minus development cruft:** - Remove `test/`, `idlelib/`, `ensurepip/`, `tkinter/`, `turtledemo/` - Remove test C extensions - Keep everything else **Use case:** Complex games, games using networking, async, etc. ### Questions for Implementation 1. **Encodings:** The `encodings/` directory has 124 files (1.8 MB). Games likely only need UTF-8. Should we strip to essentials? 2. **`__pycache__`:** Currently 3.9 MB in Lib/. Pre-compiled `.pyc` files speed startup but could be regenerated on first run. 3. **Build script approach:** - Option A: Multiple CMake build profiles - Option B: Post-build stripping script - Option C: Separate `__lib_light/` and `__lib_full/` directories 4. **Random included by default?** The issue asks this - based on usage analysis, **yes** - it's used in 8+ game files and is essential for roguelike mechanics. ### Next Steps 1. Create a stripping script that removes the definite cruft (~42 MB savings) 2. Test that McRogueFace still runs after stripping 3. Identify the true minimal set for Ultra-Light 4. Update CMakeLists.txt to support build profiles
john commented 2026-01-09 17:03:22 +00:00
Author
Owner
Copy link

a7ada7d65b - closing this feature, the actual difference between "light" and "full" is ~1MB, so I probably will only distribute the "full" stdlib. The real key to keeping distribution size down will be compressing assets.

a7ada7d65b - closing this feature, the actual difference between "light" and "full" is ~1MB, so I probably will only distribute the "full" stdlib. The real key to keeping distribution size down will be compressing assets.
john closed this issue 2026-01-09 17:03:22 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
threedee
emscripten-mcrogueface
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
0.2.3-prerelease-7drl2026-emscripten
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
priority:tier4-deferred

   
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:procgen

Procedural Generation (Noise, BSP, Heightmap)

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No labels
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
priority:tier4-deferred
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:procgen
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on
#162 [Major Feature] Cross-compilation for Windows from Linux
john/McRogueFace
Reference
john/McRogueFace#163
No description provided.