Badges Revamp

[ad-ha]

Hi,

Based on some requests (follow #115 from @mcconnell2464 ) and comments on the Badges, I have been giving some though about it and believe I will rework the Badges entirely.

My initial idea is on this is to define several Badge levels and hierarchies that allow users to manage this in an easier way.

Let's see if I can lay down this easily:

• Long-term Badges (actual points based Badges, dropping the chore count option)
• Daily Badges
• Periodic Badges (either weekly/monthly/yearly, resetting at the end of the period)
• Achievement Badges
• Challenge Badges
• Special Occasions Badges (birthday, holiday specials, etc...)
• Combined Badges (this is already over the top, but would be something like, for example, earning "Great Day" in a row for one week and a "Week Star" Badge... would grant the kids a "Super Week Star" badge)

This would also trigger some other changes:

• Reset/Expiration: some badges would reset every day or at defined periods, whilst other badges would require a minimum of points in a period to keep the badge (think about airline loyalty programs, where you need X flights/miles to keep your current status).
  This would affect Multipliers duration and Progress tracking on badges.

Anyone would like to jump on this and give some input? I plan to start working on this maybe next week, so any ideas are most welcome before I start laying down on the matter.

Cheers

[ad-ha]

To give you all a better idea of my whole though around this, here is a sample to illustrate the basics I thought of. Don't bother much with the number of points on the examples... these are just illustrative 😉

🥇 Cumulative Badges (By Points)

These badges are awarded once a kid reaches a certain lifetime (or post-baseline) total. My initial idea was that these would be permanent, but may also be tied to maintenance rules (see comment below).

Example:

• Bronze Badge:

  • Criteria: Earn 250 cumulative points
  • Reward: No multiplier bonus or a small bonus (e.g. 1.1×)
  • Maintenance (Optional): Must earn at least 500 points in any 3‑month period to maintain status

• Silver Badge:

  • Criteria: Earn 500 cumulative points
  • Reward: Moderate multiplier bonus (e.g. 1.25×)
  • Maintenance: Must earn 500+ points every 3 months or risk dropping back to Bronze

• Gold Badge:

  • Criteria: Earn 1000 cumulative points
  • Reward: Higher multiplier bonus (e.g. 1.5×)
  • Maintenance: Similar quarterly performance requirements to remain at Gold

• Platinum Badge:

  • Criteria: Earn 2000 cumulative points
  • Reward: Premium multiplier bonus (e.g. 2×)
  • Maintenance: Must sustain high performance each quarter; if not, the badge level may be reduced

Maintenance Note:
For cumulative badges, users could implement a “maintenance window” (e.g. every 3 months or X months after year-end). If a kid doesn’t earn the required minimum during that period (say 500 points), their badge could temporarily “drop” one level until they re‑qualify.

🌤️ Daily Badges

These badges encourage a kid to have a good “day” by achieving a certain amount of performance within one day. They reset every day.

Example:

• Ok Day Badge:

  • Criteria: Earn at least 15 points in one day
  • Reward: 5 additional bonus points or one reward from the integration.

• Good Day Badge:

  • Criteria: Earn at least 25 points in one day
  • Reward: 10 additional bonus points or one reward from the integration.

• Great Day Badge:

  • Criteria: Earn at least 30 points in one day
  • Reward: 15 additional bonus points or one reward from the integration.

📅 Periodic Badges (Weekly/Monthly)

These badges reward performance over a longer interval and reset with each new period.

Example:

• Weekly Star Badge:

  • Criteria: Earn at least 200 points within one week
  • Reward: 15 additional bonus points or one reward from the integration.
  • Reset: Every week at a defined day (e.g. Sunday midnight)

• Monthly Champion Badge:

  • Criteria: Earn at least 1000 points in one month
  • Reward: 25 additional bonus points or one reward from the integration.
  • Reset: Automatically resets at the start of the next month

🏆 Achievement/Challenge-Linked Badges

These badges are awarded when a specific achievement or challenge is completed. They’re directly linked to a particular achievement, so they reflect a milestone beyond regular performance metrics. This would be kept forever after the achievement or challenge is finished (even deleted)

Example:

• Chore Master Badge:
  • Criteria: Complete a defined challenge (e.g. "Complete 5 chores every day during 1-month" or "Achieve a 7‑day streak on X chore")
  • Reward: One-time reward from the integration or bonus points.

🎁 Special Occasion Badges

These badges celebrate non‑performance events. They might be manually awarded or triggered by calendar events.

Examples:

• Holiday Cheer Badge:

  • Criteria: Automatically awarded on a holiday (e.g. Christmas, Halloween) if a chore has been performed on that day.
  • Reward: A fun icon with no performance bonus, just a decorative award, for example.

• Birthday Star Badge:

  • Criteria: Awarded on the kid’s birthday (possibly manually or via integration with a calendar), if a chore has been performed on that day.
  • Reward: A fun icon with no performance bonus, just a decorative award, for example.

---

And this is pretty much a summary of my initial idea.

Feel free to jump in and share your thoughts!! 👍

[ad-ha]

A bit to early in the development, but I started shapping this:

Add steps:

Edit Cumulative Badge Menu:

There's still a long way to go, but this is getting to build up! 👍

[ccpk1]

There is a lot of good thoughts in here, but I'll add a few points and thoughts from my perspective.

1. If you plan to use points as part of this system, it's important to clarify whether they will be based on the kid's current point total or if a separate point tracking mechanism will be introduced. When you refer to cumulative points, does this mean total points earned over time (which would not decrease when rewards are redeemed), or are you referring to their current available balance?
   Using current points could discourage kids from redeeming rewards, as they might try to save points to reach a certain threshold. While this could be seen as a lesson in saving, it needs to be balanced to ensure they still redeem rewards and stay motivated.

2. I agree multiplier should only be used for longer term, otherwise it seems like it would get too complicated and confusing. One time point awards for the daily, weekly, and monthly will provide motivation, but will also be easier to manage.

3. I would probably put all of those recurring types into a single periodic badge type that allows daily, weekly, and monthly. Maybe I'm missing it, but I think they would all be used exactly the same way. It would be simpler to build as a single feature, then split out an additional use case later if there's a good reason.

4. I'd like to see the badges, specifically the periodic badges, gain the ability to track multiple specific chores, rather than just points. For instance, we have the concept of a "Good Morning" at my house. This is something we manually do now... If bookbag is ready, cat is fed, teeth are brushed all by 8:30AM, that is considered a good morning and 20 good mornings gets him a specific reward. Now in my scenario, it would be ideal if the badge criteria could also include an option to only give the badge that day if none of those things went overdue before they were claimed.

5. Tying badges into Achievements & Challenges rather than creating badge types for them.

One key limitation in current challenges and achievements is the inability to set criteria that span multiple specific chores. Right now, achievements and challenges are tied to either all goals or a single goal, depending on the type. With that in mind, I recommend removing the achievement/challenge-linked badges from this proposal as currently written for the initial phase. Instead, a more valuable approach would be to enhance the existing achievement/challenge structure by integrating a mechanism to leverage those periodic badges as criteria.

This means using daily or weekly badges to reward kids incrementally as they progress on a key group of chores, then using those to build toward full multi-week or multi-month achievement or challenge. For example, an achievement would be tracking 20 days of good mornings badges where they see those every day, but also see they are progressing on that overall achievement goal.

---

Benefits of Using Badges for Daily & Weekly Tracking While Keeping Achievements & Challenges for Mid-to-Long-Term Goals

Consistent Reinforcement of Positive Behaviors

• Kids receive frequent recognition for their progress, keeping them engaged and motivated.
• Daily and weekly badges provide immediate feedback, rather than waiting weeks to achieve a long-term challenge or achievement.
• The ability to choose a few important chores ensures focus remains on the right priorities.

Enhances Achievements & Challenges Without Adding Significant Complexity

• Badges could integrate into the existing achievement and challenge structure as another tracking mechanism, rather than relying only on points, chore counts.
• The badge system could handle the more complex tracking of multiple specific chores with additional criteria, reducing the need for additional tracking logic in achievements and challenges—at least for now.
• The badge system would also handle the periodic resets needed since this would allow achievement and challenges to be used in a more mid term fashion rather than manually changing all the time.
• This approach keeps mid-to-long-term goals structured, while still reinforcing short-term progress.

[ad-ha]

Thanks a lot for the feedback, @ccpk1. I knew that having a different perspective on this would help to get this being better, so really appreciate.

So my plan is in part, outlining from your comments.

1. Replace current badges by Cumulative Points Badges, getting rid of badges by number of chores on this end, since the mix would be complicated to manage on the long-run.

   I am still deciding (and happy to have more thoughts on this) if this should be using current points or all points earned during the time.

   At home, my older kid is currently saving points to get to the next badge. While, as you mentioned, this is affecting the way he spends on rewards, it also makes him think twice before just spending his accumulated points, which for me is kind of the way I expected him to behave and get a way to think about earnings vs expenditure. As often, each household is a world in itself.

   Solution: Set an option to define if badge is accrued on total earned points or current points, and each family may decide how to manage this. This is the best option I can think of.

2. Multipliers is a trick one. My thought on this was similar to airlines loyalty programs. Your status remains active while you keep earning enough points (miles). If you fail to do so, you go back to the badge before and if you keep failing, you go back to the other before that. Perform well again, and you raise to the next badge. Hope this makes sense.

   Again, the same thing, each family may decide if the cumulative badges reset overtime or keep indefinitely applying multipliers.

3. In my mind, separating the daily badges from periodic ones makes a bit more of sense, as it might be easier for users to digest and manage. My thought is mostly guided by the limitations with the options available to define those settings menus. Having too many fields that do not relate to daily badges (like start and end date, reset period/criteria...), may confuse the usage.

   In practice they are managed more or less similarly at the coordinator level on an everyday usage. The only major distinct part is on the configuration menus and the daily reset vs periodic (custom) resets.

4. This is an interesting one. We would have to laydown a plan on how to manage this and detail it well at an usage level in order to get it on the mix. Sometimes for us, in the heat of morning rush, I do not approve chores and do it when possible (lunch or afternoon), so this would have to have some though around it to not break the user experience.

   We can certainly add this as well. Let's lay it down and try to push for it.

5. So my idea is having this tied with Achievements and Challenges, but not inside those directly, as we will building a huge configuration step and also want to "isolate" the badges from the achievement and challenge directly, so the badges remain even if the achievement/challenge is changed or deleted once finished... so kids don't lose the badges.

   Solution: I am considering to create an on/off option in the Add Achievement/Challenge menu, so user may tell if they want to create an associated badge. If they do, this will after pop the Add Badge menu already populating the achievement/challenge name and id, to make the badge creation process easier.

6. Again, having Achievement/Challenges tracking multi-chore and badges seems a great idea. We can try to find a way to get this implemented. It doesn't sounds quite impossible. Tricky, but doable, so we just need to lay the idea and defined the inner workings and get it coded.

   My only concern is that we all get super creative with these things, that we may not be able to always cover all ideas from all users, but let's give this a shot as well.

I will have a better look into this next week, once I get a bit more of time to move it around.

Until the, we may be giving it some though and try to adapt the things to make it easier to implement 👍

Cheers

[apoldoski]

Piggybacking on the Badges discussion.

I'm struggling to get Badges to work using the Chore Count threshold type. I set up three types just as a set of test cases (1, 5, 10 Chores Completed) with no luck. I've gotten it to work with Point Totals but I can't seem to figure out how to get it to work with Chore Count as the type. Am I missing something?

[ad-ha]

Hi,

The badges are being fully rewritten, for example, the Chore Count Badges (under cumulative chores/point) will be removed and will only be available with points.

You will still have the option to award badges based on chores, but only under the new periodical badges.

It's true that the current Chore Count Badges were not fully resolve and there was a mismatch between points and chore count, so I had to simplify this bit and get the focus on the main badges to be under points only.

Cheers

[apoldoski]

No worries! I thought I had messed something up in the install and assumed it was on my end. I saw that you had planned an overhaul of the Badges but wanted to make sure you were aware of the issues in the event that it was a bug. I spent the weekend digging through through your line of code to see if I could figure out the issue on my own but I'm not too familiar with language.

I'm excited to see the progress!

[solomon0232455]

I'm happy to see this update coming. Looking forward to having an "all time" points counter!

[ad-ha]

This is getting shape, slowly as there are a lot of strings to pull and get it all together... but moving forward:

I am excited to get this out, but need to test it throughly to ensure that everything works fine. Also need to revise some sensor attributes, but it is coming all together.

[ccpk1]

Regarding the cumulative badge management, I think it is very close now, but it was a more complex than at first glance. The non-reset cumulative badges were straightforward, but figuring out an approach to handle the demotion and make it easily visible and accessible was tricky. There are a lot more data fields being stored with the kid now, but they are all under one entry, and managed in one place, so it simplifies a lot of the calculations that were being done in several locations.

🏅 Cumulative Badge System – High-Level Summary

The cumulative badge system awards kids with tiered badges (e.g., Bronze, Silver, Gold, Platinum) based on their total earned points over time. The system is designed to encourage ongoing performance while supporting maintenance cycles and clear visual tracking through Home Assistant.

---

🔍 Key Concepts

• Kids earn cumulative badges by reaching defined lifetime point thresholds.
• Once earned, the highest badge is never removed, even if the kid drops in performance.
• Instead, the system tracks a current badge, which reflects the effective badge in use — accounting for maintenance or demotion status.
• The sensor.kc_<kid>_highest_badge sensor displays:
  • The highest badge earned
  • The current (effective) badge being applied
• Each kid has a structured dictionary named DATA_KID_CUMULATIVE_BADGE_PROGRESS
  This dictionary carries all tracking information in one place for easy reference and UI access.

---

📊 Points Tracking

Each kid tracks two point totals:

• baseline: Points from all completed maintenance cycles
• cycle_points: Points earned during the current maintenance window

The sum of these two values determines cumulative badge eligibility.

---

🧠 Badge Evaluation Logic

The function _get_cumulative_badge_levels() determines:

• The current badge based on cumulative points
• The next higher badge, and how many points are needed to reach it
• The next lower badge, in case of demotion

These results are saved into the kid’s cumulative_badge_progress dictionary.

---

⚙️ Maintenance Cycle Handling

Each cumulative badge can be configured with:

• reset_type:
• maintenance_rules: The number of points required during the reset period
• grace_period: Optional days to requalify before demotion

The _manage_cumulative_badge_maintenance(kid_id) function:

• Checks whether the maintenance or grace period has ended
• Resets the cycle and baseline if the goal is met
• Moves the badge status into a "grace" for the kid if the target wasn't reached but grace days are available
• Demotes the effective badge to the next lower tier if grace is not fulfilled
• Updates the cumulative_badge_progress dictionary with:
  • Status: "active", "grace", or "demoted"
  • Updated cycle window dates
  • Reset cycle_points and updated baseline

Importantly: the highest badge is never removed — only the current badge used for multipliers and visuals is updated.

---

🗂️ Structured Tracking with DATA_KID_CUMULATIVE_BADGE_PROGRESS

Each kid has a dedicated dictionary entry that contains:

• current_badge_id, name, and threshold
• highest_earned_badge_id, name, and threshold
• next_higher_badge_id, threshold, and points_needed
• next_lower_badge_id and threshold
• Maintenance info:
  • status
  • maintenance_end_date
  • maintenance_grace_end_date
  • baseline and cycle_points

This makes data easy to access for logic and UI representation.

---

🔁 Evaluation Flow in _check_badges_for_kid

For each kid:

1. _manage_cumulative_badge_maintenance(kid_id) is run to apply any cycle rules
2. _get_cumulative_badge_progress(kid_id) is called to get the latest tracking state
3. The effective badge is checked against each badge in the system:
   • If it matches and hasn't been awarded, it is granted

Badge awards and removals are done with:

• _award_badge(kid_id, badge_id)
• badges are not removed, it uses the concept of demotion as a penalty

Updates are persisted with:

• self._persist()
• self.async_set_updated_data(self._data)

---

📅 Date Handling with _calculate_next_date()

All date math (for resets and grace periods) is handled by a single helper:

• _calculate_next_date(date_str, interval_type, amount)

Supports:

• "days", "months", "quarters", "years"
• Properly adjusts for end-of-month and leap year edge cases

📝 Open Items – Cumulative Badge System

• Determine if badge should be awarded again at every maintenance period reset
  Evaluate whether a badge should be re-awarded each time a kid qualifies at the start of a new period (especially for automation/logging).

• Assess viability of custom reset date per badge
  Custom dates may lead to unfair demotion if a badge is earned just before the reset window ends.
  Also, since badges are shared across kids, a single static custom date might not make sense when each kid earns it at a different time.

• Update logic to use current badge multiplier (not highest) when demoted
  When a badge is demoted, ensure any multiplier effects (e.g., bonus points) reference the current effective badge, not the lifetime highest.

• Ensure move from demoted status to active status happens properly, if enough points have been earned

• Determine if demotion should persist until a full maintenance cycle is completed
  Evaluate whether requiring the kid to complete another full maintenance period before reactivating the higher badge is fair, or if requalification should be immediate upon reaching the required points.

• Clean up and organize constants
  Review all constants in const.py related to cumulative badges for naming consistency, grouping, and potential de-duplication.

• Finalize date handling across all reset types
  Ensure correct calculation logic exists for:

  • Weekly
  • Monthly
  • Quarterly
  • Yearly
  • Custom (TBD)
    Validate alignment of logic, display, and maintenance resets.

[ad-ha]

Hi,

This is just great work. Thanks a lot for this. There are quite a lot of things that I did not think of and make a lot of sense.

My initial idea was to remove the highest badge from the kids if they were demoted, but keep it in log and add a demotion note makes a lot of sense, so thanks for that.

On the open items, I will try to catch up this week and help you out as well, but I am travelling for work and will not be able to do much, although I will try to do my best. The thing is that my dev instance is on a different laptop, which I use remotely to do things and declutter my daily use one (yeah, corporate policies suck...), but will get back on this.

I will also follow-up on the post with questions that you had.

Cheers