Minecraft Wiki:Style guide/Redstone

This style guide exists to establish a single convention for write-ups of redstone circuits and mechanisms.

Description
Each redstone structure should be described by some combination of text, schematic(s), and screenshot(s).


 * Structure Name
 * Structure names should be descriptive and unique, but it is not necessary to create unique names for structures which are topologically similar (they perform the same action with the same components but vary in the exact position of the blocks).


 * Screenshots and Schematics
 * Use thumbs for all screenshots and old-style (.PNG) schematics.


 * Arrangement
 * In general, the "primary" description should go to the left or top. (For English; in languages that are read right-to-left, make that "right or top".)
 * Thumbnails (screenshots and old schematics) should either go to the right in a column, or below in a gallery.
 * If a schematic is small and has a lot of text associated with it, it can also go to the right.
 * For large schematics and groups of related schematics, a long text passage can go on the left if there's room (otherwise force it to below the schematic), but if it's just brief descriptions, let those flow to the right or force them to below the schematic.
 * You can use the template to force everything following it to be below everything before it.  Make sure to use this at the end of a section/before a header.

Text
Describe any important features of the structure. Some topics to address might include:


 * Usage
 * Describe the purpose of the structure. Explain why it's used or what function it serves as part of a larger structure.
 * When writing up a number of structures which all provide the same function, consider writing the usage section only once to cover all of them. For example, if you are writing up a number of AND Gates, you could use a single usage section to discuss the purpose of AND Gates and then move on to describing the different ways to build an AND Gate without having to duplicate a discussion of their usage with each structure description.
 * Usage is the only part of the description that should be considered required for every redstone structure (or for a set of structures which provide the same function).


 * Terminology
 * Explain any new terminology used when naming or discussing a structure. If explaining the terminology would be complicated enough to overwhelm the discussion of the structure itself, consider linking to an explanation of the terminology provided somewhere else.
 * Like usage, this part of the description may be needed only once for a set of structures which provide the same function.
 * Examples:
 * Edge Detector Circuits are named for the length of the pulse they generate and for whether they detect the rising or falling edge of a pulse (or both). For example, a "1-tick Rising Edge Detector" would generate a 1-tick pulse output whenever the its input changes from OFF to ON. To further differentiate edge detectors of the same type, add more descriptive terms to the beginning of the name -- for example, "Repeater-Piston 1-tick Rising Edge Detector".
 * The T Flip-Flop is a bistable circuit (its output doesn't change until it receives new input).
 * If no new terminology is used, omit this topic.


 * Construction
 * Explain any construction details not obvious from screenshots or schematics.
 * Also explain whether there are issues that may arise due to the order in which you build a structure. Some structures will not work correctly unless certain blocks are placed in the correct order, others may (undesirably) start operating like a clock if some blocks are placed before others, etc.
 * If there are no important issues with the structure's construction, omit this topic.


 * Behavior
 * Some structures may benefit from an explanation of how they work. For example:
 * Structures which depend on the quasiconnectivity feature.
 * Structures which depend on the timing of their elements working together.
 * If behavior is obvious, omit this topic.


 * Considerations
 * Discuss any important issues with the structure. Possible considerations include:
 * Comparisons to other structures which provide the same function.
 * Material cost.
 * Compactness.
 * Behavior as a sub-structure.
 * Signal delay.
 * Pulse length modification.
 * Dependence on, or compromises due to, bugs or glitches which might be patched later.
 * Noise of: buttons, levers, pressure plates, tripwire hooks, pistons, doors, trapdoors, fence gates, dispensers, etc.
 * Possible interference with other structures.
 * If there are no important considerations, omit this topic.


 * Variations
 * Discuss significant topological variations (using the same components and mechanics, but arranged slightly differently). Minor variations don't need to be discussed if they don't offer some benfit over the original design. Use additional schematics to illustrate variations, if necessary.
 * If there are no significant variations, omit this topic.


 * Earliest Known Publication
 * List the date that the structure was first published. Cite original publication as reference.
 * If the earliest publication date is unknown, omit this topic.

Topics don't necessarily need to be titled in the structure's description -- a single paragraph might address multiple topics with a sentence each, or each topic might consist of multiple paragraphs for a complicated structure.

Schematics
Do not use animated GIFs to show multi-layer schematics. The speed of animated GIFs cannot be modified by the viewer, and not everyone can read schematics as quickly as they appear and disappear.

The preferred method for creating schematics on the wiki is the schematic template. It is permissible to upload screenshots of schematics from redstone simulator programs, but expect them to get converted by someone else later.

Add  to the caption of the first schematic in an article, and to additional schematics if that would be helpful. This will create a standard help link to Help:Schematic.

Some advice for working with the schematic template:
 * Use the standard identifiers for different roles (, , etc.) instead of your personal preferences.  These generate schematics that match the conventions used for screenshots.
 * If you have more than one kind of input or output (say, clock or control lines as well as data), mark them with overlaid letters (e.g., ), and identify their role in the text.
 * Remember to use  for blocks that will be pushed or pulled by a piston.
 * As with screenshots, if you can choose between glowstone, slab, or stairs, pick the slab.
 * Use the transparent sprites (, , and  ) for blocks that are "covering" another block. Special case: One solid block atop another can be shown by darkening the block.  If you are stacking blocks of different colors (say, a mobile block atop a solid one), note it in caption or text, as this will otherwise be unclear.
 * Any use of darkening should be explained in caption or text. For MCRS diagrams, darkening meant "solid block above"; since that has been replaced by the transparent sprites, a darkened block is now ambiguous, but can still be used to indicate occasional stacking or other situations that would otherwise require a separate level diagram.
 * Lightening is used to indicate a significant block that would not normally be shown on this level, and is not covered or underlaid by this level. Usually, that means the input and/or output blocks.
 * Multi-layer diagrams can be done two ways. Use whichever seems more understandable, but don't mix them in a single diagram.
 * Single level diagrams show all blocks, dust, and components at the same Y coordinate, with no stacking. A variation of this is the vertical diagram for 1-wide circuits.
 * Dual level diagrams show two levels at a time: Blocks, components, or empty space, but all in a two-block layer.  If there are only one or two items on a third level, you might be able to use darkening or lightening to avoid an extra layer diagram, but make sure the result is understandable.  (Then note it in caption or text anyway.)  Otherwise, don't try to cram in a third level.  For three- or more-layer circuits, do a separate Schematic template for each pair of adjacent levels:  1/2, 2/3, and so on.
 * Repeating sections of an expandable circuit can be indicated with ellipsis sprites.

Screenshots
Along with redstone schematics and written explanations, screenshots illustrate the correct way to construct redstone structures. When creating screenshots, structures should be built and shot in a consistent way so that users can quickly learn to identify which blocks in an image are part of the structure and what they do, and which blocks are there to help explain it, etc.

A screenshot can contain multiple structures if that would help to illustrate differences between different structures, or to illustrate variations of the same structure.

Building the structure

 * Background
 * Structures should be built and shot in front of a plain, non-distracting background.
 * The preferred background is a sandstone superflat world (like the Redstone Ready superflat preset), with no other blocks or mobs in the picture. Other possible backgrounds might include: the void, the sky (for under-shots, with clouds turned off), or other superflat worlds made from grass block, iron blocks, glass, etc.


 * Positioning
 * Build structures off the ground (free-floating in the air) so that they can be shot from any direction and so that it's clear exactly which blocks are part of the structure.


 * Blocks
 * Use the following blocks to build the structure and then remove all unnecessary blocks:
 * Redstone components: Use redstone torches, wire, and repeaters, as needed.
 * Opaque blocks: Use a gold block for all opaque blocks that are necessary to the structure (to support redstone torches, wire, and repeaters or to provide power to another element of the structure, etc.). For complicated redstone structures, consider using different colors of wool (instead of gold blocks) to distinguish different functional parts of the structure.
 * Moving blocks: Use a diamond block for all blocks intended to be moved by a sticky piston. This helps to illustrate the moving parts of a piston-based structure in a static screenshot.
 * Upside-down slabs: Use a stone slab for upside-down slabs required by the structure.
 * Only use upside-down slabs when they are necessary to the structure (because they can act as diodes, to avoid cutting redstone below, to avoid powering a block in that location, etc.).
 * Where an upside-down slab, upside-down stair or glowstone can be used interchangeably in a structure, use a stone slab.
 * Other blocks: Use any additional blocks required by the structure (such as pistons) or necessary to illustrate the purpose of the structure (for example, a structure intended to control a door should include the door in the screenshot).


 * Input/Output Lines
 * When it would be helpful to understand the structure, include additional blocks outside of the structure to illustrate how signals enter and exit the structure.
 * Inputs should use lime wool as a background. For structures controlled by buttons, levers, etc., use lime wool to support the power component. For structures which receive input from another sub-structure, use lime wool as the supporting block for redstone wire, redstone repeaters, etc.
 * Outputs should use pink wool as a background.
 * Buses (wire lines between structures) should be laid on white wool. Other colors may be used for multiple buses if that would improve clarity.

Taking a screenshot

 * Preparation
 * Before taking a screenshot, take the following steps:
 * Remove or deactivate mods that would affect the screenshot (unless they're specifically about a mod, all Minecraft Wiki screenshots should represent Minecraft "out-of-the-box"). Mods that wouldn't affect the screenshot, or would get cropped out later, are fine.
 * Set Texture Pack to Default (see above).
 * Set Graphics to Fancy.
 * Set FOV to Normal (the lowest setting, to minimize perspective distortions).
 * Set Particles to Minimal (to remove particles from redstone torches which might obscure or be mistaken for redstone wire).
 * Set Smooth Lighting to ON (to subdue distracting block shadows).
 * Set Clouds to OFF (only if you're intending to use the sky as a backdrop).
 * Set view to first-person (you shouldn't be in the shot). Use F5 to switch to first-person.
 * Turn off the GUI by pressing F1.


 * Taking the Shot
 * Angle: Make sure the entire structure is in the picture, including input/output lines and other illustrative blocks if present. Make sure there is additional space around the structure in your framing so that it has a nice border and you have room to do some cropping later. Try to find an angle that illustrates all important elements of the structure, but some structures may require multiple angles/shots to illustrate everything.
 * Stand on a block rather than flying over the structure. Flying expands your "field-of-view" (FOV) which increases perspective distortion, so standing is better for taking pictures. The block can be in any position that gives you a good shot, and if you need to take the picture again the block will make it easier to get back in position.
 * Make sure no mobs have wandered into frame, and that there are no other stray entities (such as dropped items) that would clutter the shot.
 * Lighting: Take screenshots in the daytime, unless necessary to illustrate a feature of the structure (if you have command privileges, use /time set 6000 to set the time to noon right before the shot).
 * Press F2 to take the screenshot (or use your own screen capture software).

Finishing up

 * Editing
 * Screenshots may need clean-up to improve clarity, but this may require some knowledge of image editing software. If you don't know how to do this, or can't, go ahead and upload your image -- hopefully someone will fix your image later (yay, wikis!).
 * Cropping: Crop the image so that the structure takes up most of the picture, but leave some border so the structure isn't crowding the edge.
 * Color Adjustment: Some screenshots may need their color adjusted to improve clarity (especially screenshots of oscilloscopes while the game is paused and dimmed).
 * File Type: All uploaded screenshots should be of type .png (Portable Network Graphic). F2 screenshots are PNGs by default, but if you use other screen capture software you may need to convert the image to a PNG with image editing software.


 * Upload the image to the Minecraft Wiki.
 * Start at the Upload File page.
 * Use the Browse button to find the image on your computer.
 * Add a description!
 * Set the Licensing menu to "This file is a screenshot of/uses textures from Minecraft".
 * Check everything and then hit the Upload File button.


 * Add the screenshot to an article.
 * Images that aren't used by articles may get deleted after a while.
 * To add a default thumb like the example screenshot above, use.
 * is the name of the file (e.g., ).
 * is the text to appear under the image.