#Balatro Modding Guide Project

1 messages · Page 1 of 1 (latest)

mighty rock
#

I'm probably not the only one that finds the barrier for entry really high when it comes to learning the fundamentals of modding Balatro. Although useful for reference, I find the SMODS wiki too abstract and not helpful for beginners.

I am thinking that we could crowd-source guides, tutorials and general tips and tricks in a GitHub repo that helps people get started with modding and learn how things are done. I am also thinking that we could take examples of mods and write about how they achieved certain things so others find it approachable.

Looking for some help on this as I am not experienced enough in the Balatro modding space but want to help myself and others get started!

https://mrdarrengriffin.github.io/BalatroModdingGuide/

delicate dome
#

literally this

mighty rock
#

But it's not useful for people wanting to know how to make mods with context. It documents the API which is great, but it's too abstract for beginners who want to get started.

azure shore
delicate dome
stone pelican
azure shore
delicate dome
mighty rock
#

Examples are cool, but again, it's not helpful if people want to understand what things do. The guides will show you a result and tell you what it takes to get there and explain things well. I like to learn not by just copying and pasting, but learning why I am doing things.

azure shore
#

Drago's example has step by step explanations (too many imo)

mighty rock
#

E.g, teaching people about using love threads to do things, creating text UI, useful hooks, example projects, telling people how mods achieved this effect.

#

Like, if you take Cryptid, I could not take the SMODS Wiki and then be able to make that mod. It would be nice if things were broken down more.

#

Just to add, I know that the wiki isn't a tutorial for how to make a specific mod, but you get my point

stone pelican
mighty rock
#

Yeah you're probably right. I think the fact that doing UI is difficult kinda put me in a state of "if only there were better guides".

delicate dome
#

what ui are you trying to do

#

because yeah i agree ui documentation is rough

mighty rock
delicate dome
#

uh huh

mighty rock
#

Pointing people to API docs isn't a great way to teach them how to use the API. It's like telling a web developer to read W3C if they want to learn web, but MDN is the better resource.

stone pelican
#

Part of the issue there is that this game's UI is bespoke and janky, and very few people are well-versed with it

mighty rock
#

I wanna bridge the gap with better guides but I'm still the homeless guy

azure shore
#

I completely agree with the sentiment but we also have this discussion every week and nobody ever makes the guides lol Also the community is not that big so the people that interact with certain parts of the code like UI is limited

If you can motivate people to do it that would be great though. I pointed you out to Drago because he wants to make something like that happen (and he's the lead dev of cryptid at the moment)

stone pelican
#

"people who know it very well" buy and large just messed around with it until it worked

azure shore
#

i still dont know what the units in the ui mean

mighty rock
#

Like for my time trial mod, if people try to make it and use a clock that uses some sleep function, their game will freeze. Who's gonna tell them that Love is the underlying framework and teach them about threads and coroutines?

#

This is the part of Lua modding I do understand from my Home Assistant project but it's so useful to know

azure shore
#

well, yeah that's part of what I'm saying. I haven't seen any mod using those so it's hard to have a guide for something maybe two people used lol

stone pelican
#

Most people use Balatro's event loop (G.E_MANAGER) instead of Love threads because concurrency just adds more complexity when asynchronicity alone will do

mighty rock
#

Yeah, I've seen that. I've mainly used threads for writing http servers that need to listen for incoming packets.

stone pelican
#

which is the same model V8 (Javascript) and asyncio (Python) use

mighty rock
#

The time trial mod can probably change to the event manager though

subtle shuttle
#

i need this

tacit warren
# mighty rock Yeah you're probably right. I think the fact that doing UI is difficult kinda pu...

Just on the UI topic specifically - Balatro's UI is just fiddly and quirky to understand when trying it for the first time. There's a (very well-written imo) UI Guide that explains almost everything you need to know to start working with it, just in case you haven't come across it yet.

I don't want to dissuade you from trying to improve the existing UI guide, but I think there's only so much that can be fully grokked by reading a wall of text, and full understanding can really only come from working with the code and learning from it directly.

mighty rock
#

Yeah, I've referenced that page quite a lot in attempt to try and figure it out. The place I fall down is where and when to call these nodes and what functions / hooks they should be against. The wiki is good at documenting the API but falls down at showing you real-life examples. They just point to peoples mods which doesn't help as they become harder to understand

tacit warren
#

I agree with that, some more in-line examples and applications of the functions would be helpful in places. It just takes a lot more effort to write up good complete examples, and the people who know it best tend to prefer to spend their time writing code instead of guides

mighty rock
#

Like, I'd be down to write the structure of the content but would need help for what code is used. I can think of many scenarios which would help people learn, but lack the knowledge on how to get there

tacit warren
# mighty rock Like, I'd be down to write the structure of the content but would need help for ...

You might currently be in the sweet spot of having enough prior knowledge to know what good documentation looks like, while being early enough in the learning stage for the Balatro codebase and SMODS to be able to ask helpful questions and give useful feedback.

If you could write a dot-point list or make a note whenever you (or other new modders) have a specific question that you can't find a well-explained answer to, it could be a good starting point for people with the motivation to improve the docs to be able to pick a small topic and chip away at it.

"Docs aren't comprehensive enough" is a common complaint, but it's hard to know where to start when most newbies don't give much actionable feedback, which is usually just scattered in #💻・modding-dev anyway. An actionable to-do list might help to avoid the common fate of wanting to overhaul the documentation only to immediately burn out when it becomes an overwhelming project.

mighty rock
#

Absolutely. Let me see if I can whip a few things up and see what you think.

My current strategy for mod making is:

  • Try to do something and fail
  • Is it on the Wiki. Kinda, but it's not enough
  • Searches Discord for examples or prior help. Too out of context or people used screenshots instead of code blocks. Nope
  • Can I find it in the game source, might fail
  • Hoping to find a mod that has my specific use case and I can use that
upbeat bolt
#

The issue with this is there is an insane amount of stiff you can do to this game that I'd either:

  • entirely in vanilla, not hard enough to use to warrant making smods replacments and not common enough to write docs for
  • not possible in vanilla, requires custom patches, not common enough or doesn't make enough sense to warrant implementating in smods
    For these you pretty much have to exclusively rely on someone
    a. Reverse engineering that particular thing
    b. Finding it difficult enough to warrant needing docs
    c. Actually care enough and have enough time to make docs.
#

If you are wanting to write docs and do need help, feel free to ask me stiff. I know how a lot of stiff works and where to find or who to ask for stuff I don't know

mighty rock
#

That's really useful. Thank you 🙂

upbeat bolt
mighty rock
#

Sounds like it!

mighty rock
mighty rock
#

I just realised why I actually want to make these guides. I find it hard to read long and very detailed articles. I have ADHD and find it difficult to read blogs and don't think I could read a book.

I think the goal for this project is to create material that is very digestible and anyone can follow. I'd like to have it so a guide on "Creating option menu buttons" be a very concise guide that looks easy to follow which has links to learn more about topics in depth for a specific step.

In the case of UI guide which is pretty overwhelming, explaining the UI system and the mechanics behind it will put people off. It's cool to make something, get it working yourself and then slowly learn more about how you made it

warped harness
mighty rock
#

I realise I forgot to push up my last commit

mighty rock
#

Okay. I was using GH wiki but I want the guides to be contributable and in source control. It now uses MKDocs deployed to GH Pages.

I'll look to create some structure and ideas for how guides could be written and poke people if I need help with the technical stuff

mighty rock
#

Struggling to find time to put effort into this. If someone wants to help, I'd be down to working on this as a collaborative project. But I am struggling to find the motivation for it. Especially considering my lack of knowledge

civic citrus
#

as someone that was looking for beginner material on making a mod for this game, something as simple as just 1 joker card example would go a long way. its all i was looking for.