Replace <a-animation> with component form

[ngokevin]

Description:

This is a well-ingrained API, and a lot of people like it. Unfortunately, I think there are too many issues with it that are inherent making <a-animation> its own Custom Element. We should consider delegating it to third-party component (I have a sample animation component on kframe). Since it's very ingrained, we'd probably give it a few versions to slowly deprecate.

Here are the issues:

• Poor Imperative Ergonomics: To add an animation imperatively, we must do createElement, multiple setAttributes, appendChild, and addEventListener('loaded').
• Asynchronous: With <a-animation>, we must wait for it to append to the DOM and register a callback listener. It's not synchronous when it could be.
• Inconsistent with the Framework: The <a-animation> tag is the only outlier in which we use a child DOM element rather than an HTML attribute to modify an entity's behavior. Components are nice because they can easily be mixed in, and you could use things like aframe-mss
• Difficult to Maintain: I made an animation component, and it is a 3-4 times smaller codebase and much simpler. This is because <a-animation> duplicates a lot of component logic related to entity lifecycles (having to handle attach, update, remove). We also have a lot of edge case code in our base classes just for <a-animation> that we could move or remove (e.g., move states from ANode to AEntity).
• Buggy: Lots of animation-related bugs that are tough to fix and often just result in adding more attributes. We don't have the manpower to maintain it when it's already fairly hard to maintain.
• Faster Development: Having animations be detached from the A-Frame core library means faster iteration. Due to being easier to maintain, having more features, and not being tied to A-Frame versions, we can do bug fixes and add features without needing to tie it to the an A-Frame release.
• Verbose (nit): A-Frame Component form is much shorter than DOM form
• Inspector: component form would be automatically compatible with the Inspector

[cvan]

are you comfortable with people using https://github.com/ngokevin/kframe/tree/master/components/animation?

honest question: why not move your component into core?

I understand the desire for faster development, but for front-end devs it's not trivial to drop in a component, unless they're comfortable with the command-line + Node/npm + Browserify. (until there's some sort of graceful component loading such as how it works with the Holodeck Club's manifest.json and ESNextbin).

I can imagine a third-party component with (even more) stock animations (i.e., canned effects) such as those defined in https://daneden.github.io/animate.css/ but for A-Frame.

[ngokevin]

Faster iteration is pretty much it. We can bump a component and release it rather than people having to wait at least a month for a new A-Frame. And we have more leniency to include additional features if it were to live as third-party. It also lets us offload work to community so that we so that we can focus on larger things because there are a lot of of costs to keeping this module (documentation, issues, support, bugs).

I think difficulty in requiring a component is a separate and larger issue. But people don't need command-line/NPM/Browserify, it's just a script tag. Front-end devs are accustomed to pulling in code via <script> tag (A-Frame being included). My brother in high school was able to grab aframe-extras with no coding experience.

I was somewhat on the fence, but I think offloading to community vs. a large batteries-included library is best long term (for now).

[ngokevin]

Forgot to answer the first question, I'm comfortable maintaining that just as I have <a-animation>. The two or so versions of deprecation will give a good buffer time as well to transition. If I don't maintain it well, naturally people can fork it (just like Blair MacIntyre forked to a better look-at component).

[cvan]

Faster iteration is pretty much it. We can bump a component and release it rather than people having to wait at least a month for a new A-Frame.

perhaps it's worth finally adopting semantic-release (which despite its name doesn't require adopting semver naming) for "continuous releases" (issue #304 covers this). if I'd have to vote, I'd place that issue high on the priority list. but you and @dmarcos definitely have a better idea of priorities.

My brother in high school was able to grab aframe-extras with no coding experience.

That's awesome and reassuring. I can actually see (and am a bit concerned) that aframe-extras becomes what the aframe core should've/could've been. Do you share those worries? I've seen with other OSS projects, it becoming a bit awkward when you need to need an additional lib to do anything "interesting."

Forgot to answer the first question, I'm comfortable maintaining that just as I have <a-animation>. The two or so versions of deprecation will give a good buffer time as well to transition. If I don't maintain it well, naturally people can fork it (just like Blair MacIntyre forked to a better look-at component).

That seems fine. I just wonder where to draw the line. Could go the stack.gl or express approach - of having micro-modules and having folks install + require each dependency. Is that the desired path of A-Frame? Or should it become (or remain?) the jQuery (a "stopgap" solution until the browsers catch up - no offence to jQuery) of WebVR for now. Is there concern that deprecating <a-animation> could sacrifice the ease of A-Frame scene development (for its hundreds+ WebVR devs/enthusiasts) in an effort to ease development of the aframe core lib (for its 71 contributors)?

Asking these questions because they're things I've wondered myself about A-Frame's vision and strategy. More precisely:

• When, if ever, will A-Frame be considered done?
• What do we need to get there?
• What is currently getting in the way? Lack of core developers/reviewers, core features, platform dependencies, curation, documentation, third-party component creators, scene creators, enough innovative scenes?

[ngokevin]

perhaps it's worth finally adopting semantic-release

semantic-release is sort of related, but if you want to pull in one fix for a single component, developers shouldn't have to worry about bumping A-Frame and having to pull all the unrelated changes with it. I'm actually sort of against continuous releases, I don't think it's right for A-Frame because releases should be fairly stable, QAed, and with documentation, which sounds hard to do. Feel free to enlighten me about continuous releases in another issue...I'm all for automating them though.

I've seen with other OSS projects, it becoming a bit awkward when you need to need an additional lib to do anything "interesting."

I don't share the worries. Every framework you're going to pull at least one dependency. It's hard to imagine if someone was able to make fireballs or mountains with a component, but were deterred by having to include a <script> tag. People'll actually want to because with a line of code, they can save themselves a ton of work (or be able to do something they couldn't otherwise). Of course, we can always ease the process. More documentation and more abstractions (Inspector, Editor, Atom plugin).

p.s., I also think it's quite beautiful that developers are adopting aframe-extras, it shows a healthy ecosystem. People are discovering it, are able to use it, gives them value, and all without us.

I just wonder where to draw the line.

Thin vs. large standard library is a legitimate question. I've thought about it over the months, and thin is best for us currently for the long term. It is sort of micro-modules, but I think that isn't necessarily a bad thing for WebVR today to enable open experimentation and to keep bundle sizes down. Component packs like aframe-extras, kframe, and perhaps our own curated pack will make this better though.

As we see more necessary things (i.e., link traversal) or unbeatable/must-have components pop up (i.e., perhaps a solid grab component, physics, controls), we can adopt more into the core or standard lib. Take it on a case-by-case basis, I don't think declarative tweening is vital or prime enough to make the cut. So don't worry too much that we're going to have a library that does absolutely nothing, it'll be plenty on its own :)

Or should it become (or remain?) the jQuery

I think three.js is already like the jQuery of 3D/VR. Grab bag of convenient modules with no opinionated structure.

Is there concern that deprecating could sacrifice the ease of A-Frame scene development (for its hundreds+ WebVR devs/enthusiasts) in an effort to ease development of the aframe core lib (for its 71 contributors)?

Deprecating <a-animation> will improve ease of development for the many performance and technical reasons mentioned above. Being able to set an animation with el.setAttribute('animation', {...}) is so much better than createElement(); setAttribute(); setAttribute(); setAttribute(); setAttribute(); appendChild(); addEventListener('loaded'). Since it's a component, you can use it via mixins, my CSS syntax in aframe-mss, or the A-Frame Inspector (which you currently can't!).

When, if ever, will A-Frame be considered done?

I think it is possible to get the A-Frame's API in a solid state since we don't have the burden of trying to enable every feature. We can have a healthy ecosystem of components, shaders, controls, primitives, etc. that are all created without hassle through that API. By that point, we should have a good story of where components live. Then we focus less on the API, and more on human-centric tools like a full Editor or VR Editor (although we have the capability to do these things in parallel).

What do we need to get there?

If we all build more scenes and components, we can continue to iterate A-Frame's API as well as gauge what is necessary to include into the core.

What is currently getting in the way?

Nothing is in the way, necessarily. We're making progress. All the above helps move things along. My itch is having more innovative scenes being built.

[cvan]

(First off, apologies for the wall of text. I'm trying to get in the habit of over-documenting things, as our team is effectively remote as is the A-Frame community.)

Awesome, this all makes perfect sense. Thanks for writing that all up. I can dig it. Personally, as someone who doesn't want to bother with build steps (though I am very comfortable with build systems), I don't want to manually add scripts (aframe.js + aframe-extras.js + …) to my scene. There are build systems out there that attempt to alleviate this (such as systemjs).

I'm asking these questions – and my apologies for my questioning (and these questions are perhaps better left to be answered in a separate issue in this repo) – in the hopes that we can keep things simple and usable. It's great to keep the A-Frame core small + elegant is great and enable developers to not have to have their components vetted by us. But I wonder if we could borrow some lessons from hapi.js and express.js).

All-in-one editor tools such as esnextbin, Thimble, and CodePen are great for prototyping (and even the first two could actually be productionised). But, today, devs still have to introduce Node + npm + the command line + Browserify/Webpack + git + GitHub if they want to create, publish, and share a scene with the world. If it's not Node + npm + the command line, it's a trial-and-error adventure of copying URLs + moving files into a directory + testing. (I know we can improve on both fronts; I touch on this later.)

I think three.js is already like the jQuery of 3D/VR. Grab bag of convenient modules with no opinionated structure.

three.js doesn't have a module system (though I know there have been attempts and arguments for/against it), but it could be considered opinionated in that it offers an anti-modular, expansive feature set.

It's certainly frustrated me that with three.js I couldn't just pick and choose modules like I can with customised jQuery/lodash builds (which admittedly causes fragmentation and makes bugs harder to trace, report, reproduce, etc.).

three.js' solution to this problem is to include everything in one giant bundle (though with Webpack/rollup.js, tree-shaking makes the problem obsolete; and also a promising contender has recently entered the ring: optimize.js) and encourage the community to build an ecosystem of examples that also live in the repository.

I agree adoption and ease of use would falter if A-Frame took the same approach. But, I will say that even npm and GitHub are suffering from the problem of "which module does what I want it to, is it compatible with the core library (and the version I'm using), do I have a guarantee that it is and will be well maintained and tested." I've heard from tweets, blog posts, podcasts, etc. that folks at both the companies are working on this problem. Curation helps for sure, but at the end of the day things need to work (most of the time).

I'd say that requiring a build step to create a scene now ups the learning curve. If you aren't moderately comfortable with the command line, Node, npm, and JavaScript, copying and pasting or downloading a third-party script (or bundle of scripts) becomes a black box.

I think it's important to support the pro-build folks and the anti-build folks. And, the anti-build folks aren't necessarily JS-naïve; they may instead want to simply invest more time in a scene than searching components, testing components, and settings things up from the command line.

I look at at stack.gl, and even with its learning resources, such as Shader School and WebGL Workshop, and I have to stop and wonder why I don't see many folks cranking out WebGL shaders/scenes (or maybe I'm looking in the wrong places). There's also regl (source), which seems to be getting some attention.

I have no doubt A-Frame will continue to thrive with its growing ecosystem of components and abundance of developers creating cool scenes.

I just hope the tools aren't getting in the way. I'm not necessarily advocating a "monorepo" (see this, this, and this), but I wonder if there's a way we can ensure that folks can compose scenes easily without having to worry about compatibility and quality (and build-step complexity).

A fair comparison I'd say is assets. There is a wildly active community of artists out there, and you can find some good assets (paid and free), but making sure they work with three.js/A-Frame out of the box requires a lot of manual work. I know there are steps we can take to automate those steps and reduce those stressors. And, I'm excited to introduce tooling to improve that process.

I just question whether scattering components and creating third-party packs improves or complicates the mental model and scaffolding of what A-Frame is, what A-Frame isn't, and when to rely on third-party modules. IMO, ease of scene creation for developers should be the #1 priority, whatever it takes.

So to bring things back, here are some ideas to solve the problems mentioned above:

1. Put non-core components in their own repos in the aframevr org (à la hapi.js and express.js).
2. Pull more and more code out of the aframevr/aframe core repo (which is exactly what express.js did over the years).
3. Continue to curate a community-driven list of "vetted" components (with extensive metadata) for easy discovery (and it could be possibly eventually automated).
4. Maintain easy component management from within the A-Frame Inspector/Editor (à la Package Control for Sublime Text, with granular flexibility for versioning/searching, etc.).
5. Build a tool like esnextbin (or commission the existing tools such as Thimble, CodePen, et. al. to properly support A-Frame goodies such as tab completion, snippets, component discovery, etc.).
6. Ensure that there exists awesome A-Frame plugins and snippets (see this one for Atom) for the commonly used text editors (and possibly IDEs) (this is possibly a good list to strive for).

[ngokevin]

But, today, devs still have to introduce Node + npm + the command line + Browserify/Webpack + git + GitHub if they want to create, publish, and share a scene with the world.

There's a bit of a tangent with the pro-build vs. anti-build in the entire comment: build steps are a barrier to adoption. Firstly, there are no build steps. I don't know why Node + NPM + Browserify are being mentioned, they are by no means required nor are they pushed over normal HTML. Secondly, people have no issue including script tags for extra features, we can see this based on how well aframe-extras has been received and been used by even the non-technical. I've seen no evidence that A-Frame or including extra features has been too difficult, and for this issue, pointing from <a-animation> to an animation component shouldn't be a large hurdle.

That being said, yeah, we can definitely improve the process. And we are! Most of your suggestions sound good, so keep those noted down.

p.s., Express and Hapi.js are not good comparisons because they are backend frameworks, adding additional code has no performance tradeoffs for them. If you look at the contrary on popular frontend frameworks, you will see a micro-module approach for non-core features.

[donmccurdy]

I have no strong opinion about whether <a-animation /> should stay in core, but:

1. Put non-core components in their own repos in the aframevr org.

That's beneficial, especially until points 3 and 4 come together. I don't particularly need to sit on aframe-extras, and if part(s) of that should be split out somehow I'm open to doing that. With loaders, for example, it's important that those components be consistent. Scattered community-driven loaders make it harder to change things, like adding model animation support.

[ngokevin]

Yeah, case-by-case basis we can maybe start introducing non-core components in the aframevr repo. That may be physics, loaders, controls, post-processing effects, etc. I think those decisions will come naturally as the needs arise.

[ngokevin]

Right now, I am starting to gather un-published components that I think are useful to re-use (e.g., the sun shader example, A-Painter landscape, reverse look controls drag) in K-Frame. Also I'm making it easy to add new things with auto-generated example pages, README, and component templates. As we learn more from this, we'll get a better idea in the future.

[cwervo]

I've been teaching workshops/giving talks on A-Frame for 8 months now & I've consistently recommended the animation component over the built in for the reasons Kevin outlined at the top of this issue, in addition to being easier for newcomers to grok.

Just wanted to chime in that <a-animation> sounds like it does more harm than good being in core & it would be good to remove if it makes maintenance harder (seems like it does) before 1.0 (even if that's not on track for 0.8, as that release train is probably happening soon)

[donmccurdy]

I'm going to add this to the 0.8.0 milestone, because animation-mixer is already there, and these two feel like they should be considered together. But also fine with me if we punt them both to the next version, instead.

EDIT: Actually, bumped to 0.9.0 after talking to dmarcos.

[ngokevin]

#3518