-
-
Notifications
You must be signed in to change notification settings - Fork 10
Project Philosophy
Mochi is one continuous little creature living on the user's desktop. Protect that illusion.
This page is the decision framework for Mochi's design and development.
It is not a substitute for explicit issue requirements or safety/security constraints. It is the default lens to use when multiple implementations could satisfy the same goal.
Mochi should feel like a small creature sharing the desktop.
Avoid turning the character into:
- a system-monitor panel
- a productivity dashboard
- a chatbot window
- a notification center
- a dense settings surface
UI should remain secondary to the creature.
A small number of behaviors that feel coherent is better than many shallow systems.
For the current phase, prioritize:
- idle presence
- tactile clicks
- expressive reactions
- pickup/drag/drop
- sleep/wake
- walking
- a few memorable emotes
Do not use feature count as a proxy for progress.
Mochi should appear to have weight, softness, and continuity.
Transitions should make visual sense:
idle → pickup → held → put-down → idle
Avoid sudden pose teleportation when an authored transition can preserve continuity.
Animations should not visibly fight each other.
Use one authoritative state/animation path.
Prefer:
current state
→ finish or safe interrupt point
→ requested state
rather than several timers independently swapping sprites.
No temporary state may become a dead end.
Examples:
- blink must return to idle
- heart must return to idle
- typing must return to idle
- pickup must reach held or recover through release
- put-down must return to idle
- wake must return to idle
Users will interact at inconvenient times. Recovery is part of the feature.
Mochi can perform quiet autonomous actions, but user intent wins.
A click, drag, or deliberate menu action should not lose to:
- blink timer
- typing timer
- random emote timer
- wandering timer
Ambient behavior should be cancellable or defer gracefully.
Canonical artwork is a project asset, not a disposable implementation detail.
Do not:
- overwrite the entire asset tree to integrate one animation
- reintroduce legacy art as an accidental fallback
- regenerate unrelated sprites to fix code
- smooth pixel art with bilinear scaling
When art must change, change the smallest relevant asset set and validate it visually.
Mochi's rendering style depends on:
- fixed logical canvas
- bottom-center anchoring
- transparent backgrounds
- nearest-neighbor rendering
- intentional pixel clusters
These are part of the design system.
Choose the simplest implementation that preserves the desired behavior.
Prefer:
- one owned timer over several clever timers
- one explicit state transition over implicit visual swaps
- a small regression test over speculative refactoring
- deterministic pixel cleanup over regenerating an entire strip
Novel architecture is not automatically better architecture.
When fixing one issue, preserve unrelated working behavior.
A request to fix pickup should not silently redesign:
- context menu
- packaging
- sleep
- asset folder structure
- UI overlay
Large cross-cutting changes require explicit intent and checkpointing.
Dev menus, previews, automation, and debugging are useful.
They must not become normal-runtime requirements.
Mochi should not need:
- remote desktop permission
- screen recording
- synthetic input permission
- development-only automation services
for ordinary use.
Wayland's security model limits arbitrary window/input control.
Do not work around platform restrictions by silently adding broad permissions.
Prefer graceful platform-specific behavior and clear limitations.
Mochi should remain lightweight.
Before adding a dependency, ask:
- Is it needed at runtime?
- Can existing GTK/Python/Cairo code do this clearly?
- Does the dependency materially improve reliability or capability?
- Does it complicate packaging?
Avoid adding a framework to solve a small problem.
Mochi should be pleasant to leave running.
Ambient behavior should be:
- infrequent
- quiet
- interruptible
- visually gentle
- not constantly demanding attention
Sound, when added, should be subtle and optional.
Context menus, nametags, and status elements should help the user without turning Mochi into an app dashboard.
Prefer contextual UI that appears when useful and disappears cleanly.
A passing test suite cannot tell whether:
- the loop visibly jumps
- a checkerboard is baked into the sprite
- the eyes look wrong
- drag feels too floaty
- pickup visually pops
Runtime behavior needs both automated tests and visual interaction testing.
The alpha is about proving the companion core.
Do not prematurely add:
- hunger
- feeding
- health
- XP
- shops
- inventory
- AI/chat
- large progression systems
unless the project scope is intentionally changed.
Before broad migrations or risky refactors:
- checkpoint
- create a backup branch if necessary
- preserve working assets
- record known-good test state
Temporary /tmp build artifacts are not durable backups.
When guidance conflicts, use this order:
- explicit user/project requirement
- safety, security, and data integrity
- this project philosophy
- implementation convenience/defaults
The philosophy should guide implementation choices, not override a deliberate requirement.
When two implementations both work, ask:
Which option makes Mochi feel more alive while keeping the application simpler, safer, and more reliable?
That is usually the right choice.
- Home
- Getting Started
- Current Development Status
- Architecture and Tech Stack
- Interaction Core
- Animation and Art Pipeline
- Development and Testing
- Troubleshooting and Regressions
- Contributing and Issues
- Roadmap and Public Alpha
- Project Philosophy
Repository: https://github.com/miflow13/mochi-desktop
Issues: https://github.com/miflow13/mochi-desktop/issues