Generate perfectly consistent and complete Python interface #126

New Issue

john · 2025-07-12T19:58:59Z

john commented

2025-07-12 19:58:59 +00:00

BASE TYPES:
---
• FONT        - sf::Font
• TEXTURE     - sf::Texture
• COLOR       - sf::Color
• VECTOR      - sf::Vector2i, sf::Vector2f
• CALLABLE    - <function>
• SOUND       - ??? handled oddly, text filenames only
• SCENE       - not sf:: (not representative of SFML object/concept)
• WINDOW      - nearly sf::
 (APIs suck for Scene and Window)


DERIVED TYPES:
---
• Timer
  └─ CALLABLE (tick callback)

• Animation
  └─ CALLABLE (done callback) *not implemented yet, but very important

• UIDrawable
  ├─ CALLABLE (click)
  └─ VECTOR (position)

• Frame
  ├─ VECTOR (size)
  └─ COLOR (outline, fill)

• Caption
  ├─ FONT
  └─ COLOR (outline, fill)

• Sprite
  ├─ TEXTURE
  └─ VECTOR (scale)

• Grid
  ├─ TEXTURE
  ├─ VECTOR (size, grid_size())
  └─ COLOR (fill) *other colors overlooked: discovered but not in FOV overlay

• Entity
  ├─ VECTOR (grid_pos())
  └─ ...sprite stuff

Extension of #20 - use mcrfpy classes:

in __init__ (see #110)
without inconvenience compared to the tuple-version of any given object (see #109)

This is the "leader issue" for a broader class of pain-in-the-ass deficiencies with the way C++ items are exposed and the way Python has to present them.

Acceptable shorthand for Python

We have these vectors across all classes:

position -> pos
- 'x' and 'y' are shorthand for pos.x and pos.y
size -> size
- 'w' and 'h' are shorthand for size.x and size.y
grid_pos and grid_size
- 'grid_x', 'grid_y', 'grid_w', and 'grid_h' match the pattern above

Similarly, we have fill and outline colors

There are a lot of other ints and floats these objects expose - they should be enumerated and made into optional __init__ keyword-only args

Mandatory args, positional args, and rules for `mcrfpy` Python objects during `init`

no args are mandatory - Caption(), Sprite(), Grid() and Frame() must result in valid, safe objects
Each object has a field or two they always need:

Sprite - Texture, index
Grid - grid_size
Entity - same as Sprite
Frame - size
Caption - font, text

The correct order for position args is [pos, size, grid_pos, grid_size vectors], [texture/font objects], [text]

Other optional args

keyword-only.

parent - see #122
name - see #39, #40, #41
children - see #38

Wiki References:

Blocked by: Need to document current patterns before automating generation

``` BASE TYPES: --- • FONT - sf::Font • TEXTURE - sf::Texture • COLOR - sf::Color • VECTOR - sf::Vector2i, sf::Vector2f • CALLABLE - <function> • SOUND - ??? handled oddly, text filenames only • SCENE - not sf:: (not representative of SFML object/concept) • WINDOW - nearly sf:: (APIs suck for Scene and Window) DERIVED TYPES: --- • Timer └─ CALLABLE (tick callback) • Animation └─ CALLABLE (done callback) *not implemented yet, but very important • UIDrawable ├─ CALLABLE (click) └─ VECTOR (position) • Frame ├─ VECTOR (size) └─ COLOR (outline, fill) • Caption ├─ FONT └─ COLOR (outline, fill) • Sprite ├─ TEXTURE └─ VECTOR (scale) • Grid ├─ TEXTURE ├─ VECTOR (size, grid_size()) └─ COLOR (fill) *other colors overlooked: discovered but not in FOV overlay • Entity ├─ VECTOR (grid_pos()) └─ ...sprite stuff ``` Extension of #20 - use mcrfpy classes: * in `__init__` (see #110) * without inconvenience compared to the tuple-version of any given object (see #109) This is the "leader issue" for a broader class of pain-in-the-ass deficiencies with the way C++ items are exposed and the way Python has to present them. # Acceptable shorthand for Python We have these vectors across all classes: * `position` -> `pos` - 'x' and 'y' are shorthand for `pos.x` and `pos.y` * `size` -> `size` - 'w' and 'h' are shorthand for `size.x` and `size.y` * `grid_pos` and `grid_size` - 'grid_x', 'grid_y', 'grid_w', and 'grid_h' match the pattern above Similarly, we have `fill` and `outline` colors There are a lot of other ints and floats these objects expose - they should be enumerated and made into optional `__init__` keyword-only args # Mandatory args, positional args, and rules for `mcrfpy` Python objects during `__init__` * no args are mandatory - `Caption()`, `Sprite()`, `Grid()` and `Frame()` must result in valid, safe objects * Each object has a field or two they always need: - Sprite - Texture, index - Grid - grid_size - Entity - same as Sprite - Frame - size - Caption - font, text * The correct order for position args is `[pos, size, grid_pos, grid_size vectors], [texture/font objects], [text]` # Other optional args keyword-only. * parent - see #122 * name - see #39, #40, #41 * children - see #38 **Wiki References:** - [Python Binding System](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Python-Binding-System) - [Adding Python Bindings](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Adding-Python-Bindings) - [UI Component Hierarchy](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/UI-Component-Hierarchy) **Blocked by:** Need to document current patterns before automating generation

john added the

Major Feature

label 2025-07-12 19:58:59 +00:00

john referenced this issue from a commit

2025-07-16 01:42:02 +00:00

Squashed commit of the following: [alpha_presentable]

john added the

Refactoring & Cleanup

system:input

workflow:blocked

labels 2025-10-26 00:44:40 +00:00

john added the