Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: support any, all and not component/tag filters on Query #3380

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

mattjennings
Copy link
Contributor

@mattjennings mattjennings commented Mar 2, 2025

⚠️ Open to any feedback. I went back and forth on a few API designs, ultimately felt this was the simplest & safest without breaking existing behavior.

Improves ex.Query to support "any" and "not" filters for components, as well as all/any/not tags filters. The intention is for this to replace ex.TagQuery, but that is not (yet) in this PR.

With this change, this would much easily allow systems to exclude entities with tags. For example, GraphicsSystem could now exclude any Entity with an ex.offscreen tag instead of manually checking in its update. This could also be used for #3076 by adding a tag to an Entity while paused that excludes it from systems.

I also removed the restriction of throwing on empty component queries, as I think it could make sense to have a system that applies for every Entity. I can change this, though.


There's also some code quality changes here.

  • I added an eslint rule to prevent fit tests (as I've accidentally committed those before)
  • an easy way to enable console logs in karma by doing CAPTURE_CONSOLE=true npm run test as I'd previously have to edit the karma config file.
  • fixed some ts errors in collider tests

===:clipboard: PR Checklist :clipboard:===

  • 📌 issue exists in github for these changes
  • 🔬 existing tests still pass
  • 🙈 code conforms to the style guide
  • 📐 new tests written and passing / old tests updated with new scenario(s)
  • 📄 changelog entry added (or not needed)

==================

Closes #

Changes:

  • Queries can now take additional options to filter in/out by components or tags.
const query = new Query({
  // all fields are optional
  components: {
    all: [ComponentA, ComponentB] as const, // important for type safety!
    any: [ComponentC, ComponentD] as const, // important for type safety!
    not: [ComponentE]
  },
  tags: {
    all: ['tagA', 'tagB'],
    any: ['tagC', 'tagD'],
    not: ['tagE']
  }
})

// previous constructor type still works and is shorthand for components.all
new Query([ComponentA, ComponentB] as const)
  • Queries can now match all entities by specifying no filters
const query = new Query({})

@mattjennings mattjennings requested a review from eonarheim March 2, 2025 22:04
@github-actions github-actions bot added the enhancement Label applied to enhancements or improvements to existing features label Mar 2, 2025
@mattjennings
Copy link
Contributor Author

mattjennings commented Mar 2, 2025

This was partially inspired by Unity's EntityQueryBuilder although I didn't include an actual builder API.

var query = new EntityQueryBuilder(Allocator.Temp)
    .WithAll<ObjectPosition, ObjectRotation>()
    .WithAny<Melee, Ranger>()
    .WithNone<Player>()
    .Build(this);

Copy link

cloudflare-workers-and-pages bot commented Mar 2, 2025

Deploying excaliburjs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 8f7089f
Status: ✅  Deploy successful!
Preview URL: https://7f2816ae.excaliburjs.pages.dev
Branch Preview URL: https://feat-refactor-queries-filter.excaliburjs.pages.dev

View logs

@mattjennings mattjennings changed the title reat: support any, all and not component/tag filters on Query feat: support any, all and not component/tag filters on Query Mar 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Label applied to enhancements or improvements to existing features
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant