Naninhas came from a very simple idea: if attachable plushies already add personality to a character, why not let them add gameplay value too?
Project Zomboid is full of systems that make small choices matter. Clothing matters. Inventory matters. Traits matter. Moodles matter. So the idea behind Naninhas was to take something playful and cosmetic from Authentic Z and turn it into something mechanical without losing the charm that made it fun in the first place.
That became the core concept of the mod:
attach a plushie to your backpack, and while it stays equipped, it grants a themed gameplay bonus.
Some plushies grant traits. Some suppress opposing traits. Some affect stats. Some give XP bonuses. The intention was never to make plushies overpowered. The goal was to make them feel meaningful.
Where the idea started
This mod originally started around the Build 41 era.
At the time, the concept was already clear: use attachable plushies from Authentic Z as lightweight character buffs, something flavorful and useful that fits naturally into a normal playthrough. But as often happens with Project Zomboid modding, a simple gameplay idea becomes much more interesting once you start dealing with real game APIs, real save-state concerns, and version differences across builds.
When Build 42 entered the picture, the project had to evolve with it.
That was not just a matter of changing a couple of names and recompiling. Build 42 introduced API differences, changed how some runtime systems behave, and pushed me to make the mod more rigorous in places that could be looser before.
In the end, that was a good thing. Build 42 made the mod better.
What Naninhas is trying to be
Naninhas is not meant to be a total rebalance or a progression overhaul.
It is meant to be:
small in scope
thematic
cleanly integrated
safe to use in real saves
easy to understand as a player
That design philosophy influenced almost every decision.
Each plushie effect is intended to feel like a natural extension of the plushieâs identity. The bonus should be useful, but not absurd. It should feel like a nice character detail, not a broken exploit.
That balance matters a lot in a game like Project Zomboid, because even small passive effects can become very strong if they stack badly, persist incorrectly, or interact unpredictably with traits and XP systems.
The real work was not just âadding buffsâ
From the outside, the feature sounds straightforward:
detect attached plushies
assign a bonus
remove it when unequipped
But the hard part is never the first application. The hard part is cleanup and consistency.
That means questions like:
how do we make sure a trait is removed when the plushie is unequipped?
how do we avoid permanently modifying the player state?
how do we stop XP multipliers from drifting over time?
how do we make repeated periodic updates safe?
how do we survive save/load cycles without leaving residue behind?
A mod like this can feel fine in the first ten minutes and still quietly break a long save if these details are not handled carefully.
So a lot of the work in Naninhas went into state tracking and safe removal.
Traits added by the mod are tracked. Suppressed traits are tracked. XP boosts are applied with persisted target values and delta logic so they do not keep stacking accidentally. That kind of invisible engineering is what makes the feature feel stable.
Players should only notice the effect, not the machinery behind it.
The Build 42 challenge
One of the biggest technical shifts came from supporting Build 42 properly.
Build 42 pushed me to revisit how trait handling worked. Older assumptions around strings and simpler lookups were no longer enough if I wanted the mod to behave correctly against the newer APIs.
That led to a deeper cleanup pass:
updating trait integration to match Build 42 behavior
improving local type definitions
reducing unsafe casting
verifying how trait collections actually behave in the game
tightening logic around known traits and trait object resolution
That kind of work is not flashy, but it matters.
If the code lies about what the game API actually returns, the mod becomes harder to maintain and easier to break. So one important part of the process was making the code describe the real runtime behavior more honestly.
That improved both reliability and readability.
The tech stack I chose
Naninhas is built with a TypeScript-to-Lua workflow using PipeWrench.
That stack was a deliberate choice.
Why TypeScript-to-Lua
Project Zomboid modding traditionally leans heavily on Lua, and for good reason: it is what the game uses, it is flexible, and it integrates directly with the modding ecosystem.
But for a project like Naninhas, TypeScript-to-Lua gave me some real advantages:
stronger structure for larger codebases
easier refactoring
safer modeling of domain logic
better separation between systems
improved testability
typed wrappers around game-facing behavior
For a mod that deals with temporary state, traits, XP boosts, observers, and periodic update loops, having stronger structure pays off quickly.
Why PipeWrench
PipeWrench made that workflow practical.
Using PipeWrench meant I could write mod logic in TypeScript while still targeting Project Zomboidâs Lua runtime. That gave me a better engineering experience without losing compatibility with the gameâs scripting model.
It also made it easier to:
organize code into modules
build cleaner abstractions
mock game-bound logic for tests (yes, I've added unit tests into this project)
keep the project maintainable as features grew
That is a big deal when the project starts as âjust a small modâ and slowly becomes a real codebase.
Shout-outs
This mod would not exist in its current form without the work of other creators in the Project Zomboid community.
First, a shout-out to AuthenticPeach, the creator of Authentic Z.
Authentic Z already adds a huge amount of identity and style to the game, and the attachable plushies were the spark that made Naninhas possible in the first place. The entire mod idea comes from wanting to build on top of that creative foundation in a respectful way.
Also, a shout-out to asledgehammer for PipeWrench.
PipeWrench made it possible to approach Project Zomboid modding with a more structured TypeScript workflow, and that had a huge impact on how this project was built. A lot of the maintainability and confidence in the code comes from having that tooling available.
The architecture behind the mod
One thing I wanted from the beginning was for the code to stay understandable as the mod expanded.
That meant avoiding a giant pile of conditionals for every plushie and instead leaning into a more modular design:
a core Naninhas system that scans attached items
individual plushie classes responsible for their own behavior
shared player-facing abstractions
tracked mod data for safe cleanup
observer-style update flow for active effects
That structure made it easier to add new plushies without rewriting the whole system every time.
It also helped keep the gameplay logic separate from the game-bound plumbing, which is especially helpful when testing or adjusting Build 42-specific integrations.
Testing mattered more than expected
Another lesson from this project is that even small gameplay mods benefit a lot from tests.
The more stateful a feature is, the easier it is to accidentally introduce regressions:
effects not being removed
traits resolving incorrectly
unsupported cases being handled poorly
update loops subscribing or unsubscribing at the wrong time
Having tests around the modâs core behavior made it much easier to evolve the code without second-guessing every change.
For a mod that started from a fun idea, it ended up becoming a good reminder that polish comes from discipline.
Releasing the mod was also part of the work
Finishing a mod is not just getting the code to run.
There is also the release layer:
metadata
compatibility notes
Workshop formatting
translations
screenshots
README clarity
support links
messaging around requirements and compatibility
A polished mod page matters because it lowers friction. Players should understand what the mod does, what it needs, and how it fits into their setup without having to dig through comments or guess.
That is part of the development process too.
What I like most about this project
What I like most about Naninhas is that it sits in a nice middle ground.
It is playful, but it still respects the gameâs systems.
It adds flavor, but it still has mechanical weight.
It started as a small mod idea, but it became a chance to build something cleanly.
That combination is the sweet spot I enjoy most in modding.
Check out the project!
Support the project
If you like this kind of modding work, and if you want to support the ongoing development of Naninhas and future updates, you can support the project here! - Buy Me a Coffee
Thanks for checking out the project, and thanks to everyone who downloads, tests, reports issues, and shares feedback.